La documentation simplifiée avec reST

introduction et exemples d'utilisation

Table des matières

Note

Ce document est une présentation de l'outil reST, qui est un outil facilitant la mise en forme de documents. Il permet de générer, à partir d'un simple fichier texte, des pages dans plusieurs formats (html, pdf, ...), dont le style peut être facilement modifié.

1   Qu'est-ce que reST ?

1.1   Présentation

reST signifie reStructuredText, c'est un langage "à balises" (markup language en anglais), au même titre que HTML, XML, ou encore TeX. La différence principale avec ces autres langages est que reST est bien plus léger, c'est-à-dire que ses balises ne sont pas intrusives comme peuvent l'être celles du HTML par exemple. En fait, reST se rapproche plus des pseudo-langages utilisés pour la rédaction d'articles dans les wiki. Sa syntaxe est vraiment très simple et elle sait se faire oublier lorsque l'on lit le code source d'un document reST. De plus, la syntaxe est assez intuitive, et apprendre ce langage est un processus rapide.

Un petit exemple valant mieux qu'un long discours, voici comment on écrirait un titre en TeX:

@section{Le titre de mon document}

et voici la même chose avec reST:

Le titre de mon document
------------------------

La seconde version est plus lisible, et ce n'est pas ceux qui ont écrit leur thèse avec LaTeX qui me contrediront (je sais de quoi je parle)... Vous pouvez aussi regarder le code source qui a été écrit pour générer cette page.

1.2   Historique

A l'origine, reST a été développé dans le cadre du module docutils du langage Python, docutils qui est le framework permettant d'effectuer toutes sortes de traitements sur les fichiers textes. Des parsers ont été développés depuis dans d'autres langages, comme Java avec jrst par exemple. Aujourd'hui, reST est le format utilisé pour écrire la documentation officielle de plusieurs projets, comme Python, ou Zope, pour ne citer que les plus connus.

Pour une présentation plus détaillées des buts et de l'origine de ce langage, vous pouvez vous réferer au lien suivant : [reST_History].

1.3   Principe de fonctionnement

Le principe de fonctionnement de reST est le suivant :

1. L'utilisateur édite un fichier texte avec n'importe quel éditeur, et ajoute à son texte certaines balises qui se rapportent à la sémantique de celui-ci. Ces balises permettront à reST de mettre en forme le texte de manière appropriée.

2. L'utilisateur soumet son texte au parser reST, et lui spécifie le format de sortie qu'il désire obtenir. Dans le cadre de ce document, c'est du HTML qui a été demandé, mais on aurait pu obtenir d'autres formats.

2   Comment utiliser reST ?

2.1   L'installation

Pour utiliser reST, il faut installer le paquet docutils de Python, et donc le langage Python également. Sur une machine Debian, le paquet à installer s'appelle python-docutils. Sur une machine FreeBSD, le ports à compiler s'appelle py-docutils, il se trouve dans le répertoire /usr/ports/textproc.

Une fois que docutils a été installé, plusieurs commandes sont disponibles, dont rst2html, rst2s5, rst2latex, ... Ces commandes permettent de convertir un fichier reST (d'où les 3 lettres rst en début de chaque commande) en d'autres formats comme le html (rst2html) par exemple.

Note

A noter que reST permet aussi de générer des slides pour mettre en ligne une présentation. Pour un exemple, vous pouvez trouver dans la partie packaging de ma documentation rassemblée sur tekos une présentation de l'outil epm qui a été réalisée avec reST. Est également indiqué le code source qui a permit de créer cette présentation. Si vous voulez plus de renseignements concernant les possibilités offertes par reST pour mettre en ligne vos slides, vous pouvez consulter le site [reST_s5].

2.2   L'utilisation

La première étape est d'écrire son texte en utilisant les balises présentées ci-dessous. Une fois que votre texte est prêt, il faut appeler le convertisseur reST pour créer le fichier au format voulu. Si par exemple on veut créer une page web, la commande à utiliser sera rst2html. Ainsi, si l'on a un texte appelé texte_origine.txt, on tapera la commande suivante:

rst2html texte_origine.txt > texte_formate.html

et le document texte_formate.html sera une page web construite à partir de notre fichier source. Par défaut, une feuille de style fournie avec le paquet docutils est utilisée, mais vous pouvez également spécifier votre propre feuille de style. Dans ce cas la commande à utiliser est la suivante:

rst2html --stylesheet-path=chemin_vers_mon_css texte_origine.txt > texte_formate.html

A titre d'exemple, la feuille de style utilisée pour la présente documentation est visible en suivant ce lien.

En annexe vous trouverez un Makefile simple qui permet de générer tous les fichiers ayant une extension .txt dans le répertoire courant en page web avec reST.

2.3   Le format reST

La page quickref présente de manière synthétique la plupart des balises utilisées par reST, avec d'un côté le texte source à taper, et en face le rendu final qui sera généré par reST. C'est un bon exemple pour qui veut se rendre compte de ce qu'il est possible de faire avec ce processeur de texte.

Pour vous donner un bref aperçu, voici le code source d'un texte et le résultat une fois formaté avec reST:

Texte d'origine Texte formaté avec reST
Un exemple de liste :

* premier élement

  1. sous-élement
  2. sous-élement

* deuxième élement

Un exemple de tableau :

+----------+---------+----------+
|  titre 1 | titre 2 | titre 3  |
+----------+---------+----------+
|  case 1  |                    |
+----------+       case 4       |
|  case 2  +---------+----------+
+----------+         |          |
|  case 3  |  case 5 |  case 6  |
+----------+---------+----------+

différents styles de texte :

*important*, **très important**,
``code source``, etc.

un lien hypertexte :

http://culot.org

utiliser des macros :

date : |date|

Un exemple de liste :

  • premier élement
    1. sous-élement
    2. sous-élement
  • deuxième élement

Un exemple de tableau :

titre 1 titre 2 titre 3
case 1 case 4
case 2
case 5 case 6
case 3

différents styles de texte :

important, très important, code source, etc.

un lien hypertexte :

http://culot.org

utiliser des macros :

date : 30 Jul 2008 15:32

Voici un bref aperçu de ce qu'il est possible de faire avec reST. Comme on le voit, le texte d'origine reste très lisible. Mais cet outil est bien plus puissant que cela. En effet, il permet entre autres de générer une table des matières automatiquement, en numérotant les sections, sous-sections, etc. Il peut également numéroter les notes de bas de pages automatiquement, insérer des images dans le document, il est aussi possible d'insérer des commentaires dans le source qui n'apparaitront pas dans le document final, ...

Bref, pour une liste complète de tout ce qu'il est possible d'utiliser avec ce format, vous pouvez vous réferer aux spécifications de reST.

D'autre part, si vous voulez essayer des commandes reST et prévisualiser le résultat simplement pour vous rendre compte du rendu, vous pouvez vous rendre à l'adresse suivante : [reST_previ], qui transforme en ligne le fichier texte que vous tapez dans l'interface.

3   En savoir plus

3.1   La documentation

Ce lien résume les différentes balises de manière synthétique. Vous pouvez enregistrer puis formater cette page avec reST pour voir le résultat.

3.2   Les liens

Voici une liste de liens pour qui voudrait approfondir le sujet.

Sphinx

un framework récent qui permet non seulement de formater une unique page comme la commande rst2html, mais aussi construire des documents complexes de plusieurs centaines de pages.

http://sphinx.pocoo.org/

rst2a

une API sous forme de web service qui permet de transformer sans rien devoir installer en local ses documents reST.

http://rst2a.com/

VST

un moteur de rendu reST directement integré à vim

http://skawina.eu.org/mikolaj/vst.html

rst-mode

le support de reST dans emacs

http://docutils.sourceforge.net/docs/user/emacs.html

4   Annexe

4.1   Makefile pour la génération de pages web

Ce Makefile est à utiliser pour transformer les fichiers .txt du répertoire courant en fichier html. Ces pages web générées sont placées dans un répertoire nommé html. Il faut placer également une feuille de style nommée docutils.css dans le répertoire courant, qui définit le format d'affichage utilisé pour créer les pages web. En tapant la commande make install, il est également possible de déposer simplement les pages web générées sur une machine distante (il faut pour cela avoir les clés ssh déployées de manière adéquate, et définir correctement la variable INSTALLDIR).

textfiles = $(wildcard *.txt)
htmlfiles := $(patsubst %.txt,%.html,$(textfiles))
CSSFILE := ./docutils.css
INSTALLDIR = machine_distante:repertoire_distant
OBJDIR = html

.PHONY: all clean install objdir html

all: objdir html

$(htmlfiles): %.html: %.txt
       rst2html --stylesheet-path=$(CSSFILE) $< > $(OBJDIR)/$@

html: $(htmlfiles)

objdir:
       @mkdir -p $(OBJDIR)

install: html
       scp $(OBJDIR)/$(htmlfiles) $(INSTALLDIR)

clean:
       @rm -f $(OBJDIR)/$(htmlfiles)
       @rm -rf $(OBJDIR)

[reST_History]http://docutils.sourceforge.net/docs/ref/rst/introduction.html
[reST_s5]http://docutils.sourceforge.net/docs/user/slide-shows.s5.html
[reST_previ]http://www.hosting4u.cz/jbar/rest/rest.html