Un Electron Libre...

Dans le monde python, il y a :

• Une syntaxe de documentation puissante mais pas aisée à prendre en main : ReST, pour ReStructured Text, fourni via docutils. Voir la QuickRef de ReST.
• Pygments, un système de coloration syntaxique, un peu comme GeSHi en PHP.

Dans vos documents rédigés en ReST, il est possible d'inclure Pygments pour enrichir le rendu de vos documents.

Il vous faut pour cela :

• docutils installé sur votre ordinateur,
• pygments aussi
• récupéré le fichier external/rst-directive.py présent dans le fichier source de pygments 0.9 et le copier dans /usr/lib/python2.5/site-packages/docutils/parsers/rst/directives/

Ensuite, et c'est là où le système manque un peu de flexibilité, il faut déclarer cette directive :

• Editer /usr/lib/python2.5/site-packages/docutils/parsers/rst/directives/init.py (il y a deux "_" de chaque coté du init - bug de DC2 apparemment) pour ajouter une ligne :

_directive_registry = {
      'sourcecode': ('rst-directive', 'pygments_directive'),
      'attention': ('admonitions', 'Attention'),
      ...
      }

Cette déclaration dit que quand j'utiliserais la directive sourcecode dans mon document ReST, alors il doit aller utiliser la classe pygments_directive présente dans le fichier rst-directive.py.

• Editer le fichier /usr/lib/python2.5/site-packages/docutils/parsers/rst/languages/en.py (et les éventuelles traductions) :

directives = {
      # language-dependent: fixed
      'sourcecode': 'sourcecode',
      'attention': 'attention',
      ...
      }

Voilà pour l'installation de pygments et docutils.

Dans votre texte au format ReST, il vous suffit d'utiliser la directive sourcecode comme dans l'exemple suivant :

Tutoriel : partie 1
===================

settings.py
-----------

.. sourcecode:: python

    # Django settings for tutoriel project.

    DEBUG = True
    TEMPLATE_DEBUG = DEBUG

    ADMINS = (
        # ('Your Name', 'your_email@domain.com'),
    )

Si vous voulez que les numéros de lignes soient également mentionnés, il vous faut décommenter la ligne suivante (dans rst-directives.py) :

et modifier votre fichier de la façon suivante (ajout de la directive :linenos: :

Tutoriel : partie 1
===================

settings.py
-----------

.. sourcecode:: python
    :linenos:

    # Django settings for tutoriel project.

    DEBUG = True
    TEMPLATE_DEBUG = DEBUG

    ADMINS = (
        # ('Your Name', 'your_email@domain.com'),
    )

Je vous fais grâce du code html de rendu, surtout que pour le moment, je n'ai pas de coloration syntaxique (cf Pygments et ReST Partie 2)