Réaliser de la documentation avec docutils et/ou sphinx
Doctutils est une suite d'outils permettant la transformation d'un texte intelligible, grâce à une syntaxe qui lui est propre, en plusieurs formats tels que le HTML ou le LaTeX.
La syntaxe utilisée est le reStructuredText que l'on écrit aussi reST.
Installation
Le nom du paquet à installer est python-docutils à adapter en fonction de votre distribution GNU/Linux.
# urpmi python-docutils
Edition
$ mkdir doc
$ cd doc
Prenez votre éditeur de prédilection :
$ vim essai.txt
essai de titre
==============
sous-titre
----------
bla bla
- liste 1
- item 2
- item 3
deuxième sous-titre
-------------------
bla bla
::
ls /tmp
cd /usr/bin
Pour créer un titre, souligner le avec le caractère de votre choix.
Pour faire un sous-titre, souligner le avec un autre caractère de votre choix.
Pour faire une liste utiliser simplement des tirets.
Pour créer un bloc, utiliser :: suivit du contenu avec un retrait.
Il est possible d'exporter votre travail vers html, man, odt, pseudoxml, xml, latex et s5.
Vim est en mesure d'apporter la coloration syntaxique, pour l'y aider vous pouvez donner l'extension .rst plutôt que .txt.
Exporter
Nous pouvons maintenant exporter notre document dans le format HTML :
$ rst2html essai.txt > essai.html
Vous pouvez maintenant visualiser le résultat dans votre navigateur :
$ firefox essai.html
Voici d'autres balises pour docutils :
http://docutils.sourceforge.net/sandbox/wilk/french/quickstart-fr.html
Essayons maintenant avec sphinx. C'est un outil de génération de documentation pour les projets Python.
Installation
# urpmi python-sphinx
Liens
Site de docutils :
http://docutils.sourceforge.net/
Le guide de démarrage rapide de rST :