Skip to Content

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 :

http://docutils.sourceforge.net/docs/user/rst/quickref.html