======================================= La documentation simplifiée avec *reST* ======================================= -------------------------------------- introduction et exemples d'utilisation -------------------------------------- .. sectnum:: .. contents:: 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é. Qu'est-ce que reST ? ==================== 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 <./documentation_rest.txt>`_ qui a été écrit pour générer cette page. 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]_. 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. Comment utiliser reST ? ======================= 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]_. 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 <./docutils.css>`_. 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*. 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 : | Un exemple de liste : | | | | | * premier élement | * premier élement | | | | | 1. sous-élement | 1. sous-élement | | 2. sous-élement | 2. sous-élement | | | | | * deuxième élement | * deuxième élement | | | | | Un exemple de tableau : | Un exemple de tableau : | | | | | +----------+---------+----------+ | +----------+---------+----------+ | | | titre 1 | titre 2 | titre 3 | | | titre 1 | titre 2 | titre 3 | | | +----------+---------+----------+ | +----------+---------+----------+ | | | case 1 | | | | case 1 | | | | +----------+ case 4 | | +----------+ case 4 | | | | case 2 +---------+----------+ | | case 2 +---------+----------+ | | +----------+ | | | +----------+ | | | | | case 3 | case 5 | case 6 | | | case 3 | case 5 | case 6 | | | +----------+---------+----------+ | +----------+---------+----------+ | | | | | différents styles de texte : | différents styles de texte : | | | | | *important*, **très important**, | *important*, **très important**, | | ``code source``, etc. | ``code source``, etc. | | | | | un lien hypertexte : | un lien hypertexte : | | | | | http://culot.org | http://culot.org | | | | | utiliser des macros : | utiliser des macros : | | | | | date : |date| | date : |date| | | | | +------------------------------------+------------------------------------+ 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. En savoir plus ============== 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. 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 Annexe ====== 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) ---------------- .. _jrst: http://jrst.labs.libre-entreprise.org/ .. _Python: http://docs.python.org/dev/ .. _Zope: http://docs.carduner.net/z3c-tutorial/ .. [reST_History] http://docutils.sourceforge.net/docs/ref/rst/introduction.html .. [reST_s5] http://docutils.sourceforge.net/docs/user/slide-shows.s5.html .. _quickref: http://docutils.sourceforge.net/docs/user/rst/quickref.html .. _spécifications: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html .. [reST_previ] http://www.hosting4u.cz/jbar/rest/rest.html .. _lien: http://docutils.sourceforge.net/docs/user/rst/cheatsheet.txt .. footer:: - Dernière mise à jour : |date| .. |date| date:: %d %b %Y %R