Les bases de reStructuredText¶

Introduction¶

Ce document est une introduction informelle à reStructuredText (reST), qui est un langage de balisage de texte. Le texte reST est interprété (p. ex., par Sphinx) pour produire des documents HTML pouvant être lus par un navigateur.

Ne pas hésiter à afficher le code source de la page pour comprendre quelle est la syntaxe utilisée.

L’entité la plus basique est le paragraphe. C’est un bloc de texte séparé par des lignes vides (une suffit). Il faut noter qu’il n’est pas possible d’aller à la ligne à l’intérieur d’un bloc de texte (voir plus loin le non-effet du passage à la ligne). Les paragraphes doivent avoir la même indentation -i.e., être alignés à gauche. Des paragraphes qui sont décalés par rapport aux précédents sont traités comme des citations. Par exemple :

Ceci est un paragraphe, il est plutôt court

Ce paragraphe indenté va être rendu comme un bloc en retrait, idéal pour les citations.

Là on revient à la ligne.

Styles de texte¶

Dans les paragraphes et autres entités textuelles, il est possible de marquer du texte en italiques avec *italiques* ou en gras avec **gras**, ou encore partiellement ainsi : **partielle**\ment. Ce sont des balises dans le texte (inline markup) ; pour le faire .

Pour faire apparaître du texte en police à empattement fixe, utiliser de doubles guillemets : texte à empattement fixe (justement utilisés pour signaler les commandes reST dans ce document). Noter qu’aucun bidouillage supplémentaire ne peut être fait à l’intérieur de tels guillemets (p. ex., pas d’italiques).

Pour utiliser l’un de ces caractères “spéciaux” dans le texte, il suffit de le faire précéder d’un antislash comme ceci : 5\*6=30, qui sera rendu ainsi : 5*6=30.

Astuce¶

Il faut considérer que le balisage en ligne est une forme de parenthésage et qu’il doit être utilisé en tant que tel : immédiatement avant et après le texte que l’on veut marquer (sans insérer d’espaces, ni au milieu d’un mot).

Listes¶

Les listes d’items sont de trois sortes : énumération, à puces, définitions. Pour toutes ces listes on peut avoir autant de paragraphes et de sous-listes que l’on veut, du moment que le côté gauche de leur paragraphe est aligné avec la première ligne de texte.

Les listes doivent toujours démarrer comme un nouveau paragraphe (après une ligne vide).

\A. Einstein est un gars vraiment très intelligent

Préformatage (code informatique)¶

Pour inclure un paragraphe de texte préformaté, terminer le bloc par ”::”. Le bloc préformaté qui suivra sera terminé quand le texte reviendra au même niveau d’indentation que le texte juste avant le bloc préformaté. Et les deux deux-points sont convertis en un simple deux-points s’ils ne sont pas précédés d’une espace. L’exemple, ci-dessous débute par Un exemple::. Si une espace est mis avant les :: ils n’apparaissent pas.

Un exemple:

      Espaces, retour-chariot, toute sorte de balisage (comme *celui-ci* ou \celui-ci) sont préservés dans de tels blocs.
Voyez comme j'ai changé de niveau d'indentation
(mais pas suffisamment pour sortir du bloc)

Là, j’en suis sorti !

Noter que si un paragraphe consiste seulement en ”::”, il sera supprimé de l’output (donc pas rendu):

Voici du texte préformaté, mais le premier "::" paragraphe est supprimé

Sections¶

Plus d’informations ici

Pour organiser du texte long en sections, vous pouvez utiliser des titres de section. Ce sont de simples lignes de texte (un ou plusieurs mots) avec une décoration spécifique : avant ou après le titre, avec des tirets, des signes égal, des tildes, ou tout caractère non-alphanumérique : = - `‘ ” _ + # < > qui plaît. Une décoration seulement sous le titre est distincte de la même décoration utilisée sur et sous le titre. La décoration doit avoir la même longueur que le texte. Utiliser les décorations de manière cohérente, car tous les titres de sections avec la même décoration sont censés être au même niveau de titre.

Titre chapitre 1¶

Titre Chapitre 2¶

Il faut noter que chaque titre peut aussi être utilisé comme cible d’un lien interne au document, en utilisant simplement son nom. Pour créer un lien hypertexte avec un titre du document, écrire simplement `Titre Chapitre 2`_ pour avoir le lien Titre Chapitre 2.

Titre du document/sous-titre¶

Le titre du document entier est distinct des titres des sections et doit être formaté d’une manière différente. Utiliser une décoration unique au début du document pour son titre. Utiliser une autre décoration unique immédiatement après le titre du document. Par exemple :

Section 1¶

Noter que les titres du document et de section utilisent tous deux des signes “=” mais ce sont des styles non reliés. Le texte des titres décoré au-dessus et au-dessous peuvent être indentés par souci d’esthétique.

Séparation¶

Une séparation (rendue en HTML avec la balise <hr>) se crée avec la répétition d’au moins 4 caractères de ponctuation, séparée de lignes vides

paragraphe

----

paragraphe

se rend ainsi :

paragraphe

paragraphe

Commentaires¶

Pour insérer un commentaire qui ne sera pas traité par reST ou Sphinx, faire débuter le paragraphe par ”..”.

Tableaux¶

Plus d’informations ici

Il y a plusieurs manières de construire des tableaux avec reST et aucune n’est aisée, notamment lorsque les tableaux sont complexes.

====  ====  ========
A     B     A et B
----------  --------
 \          a et b
====  ====  ========
Faux  Faux  Faux
Vrai  Faux  Faux
====  ====  ========

.. csv-table:: Délices glacés!
        :header: "Produit", "Quantité", "Description"
        :widths: 15, 10, 30

        "Albatross", 2.99, "On a stick!"
        "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
         crunchy, now would it?"
        "Gannet Ripple", 1.99, "On a stick!"

.. list-table:: Délices glacés!
   :widths: 15 10 30
   :header-rows: 1

   * - Produit
     - Quantité
     - Description
   * - Albatross
     - 2.99
     - On a stick!
   * - Crunchy Frog
     - 1.49
     - If we took the bones out, it wouldn't be
       crunchy, now would it?
   * - Gannet Ripple
     - 1.99
     - On a stick!

+------------------------+------------+----------+
| Header row, column 1   | Header 2   | Header 3 |
+========================+============+==========+
| body row 1, column 1   | column 2   | column 3 |
+------------------------+------------+----------+
| body row 2             | Cells may span        |
+------------------------+-----------------------+

Notes de bas de page¶

L’appel d’une note de bas de page peut être :

• un nombre d’un ou plusieurs chiffres ;
• un “#” pour des notes numérotées automatiquement ;

L’appel est inséré ainsi dans le texte [1]_, rendu par un lien hypertexte cliquable : [1]. Chaque corps de note démarre par un double point ”..”, une espace l’un des appels ci-dessus entre crochets, une espace, suivi par le corps de la note. Ce dernier est indenté d’au moins 3 espaces et aligné à gauche. Le corps peut être placé n’importe où dans le document (pas seulement à sa fin):

.. [1] Je suis un corps de note de bas de page.

est rendu ainsi :

Liens hypertextes¶

Nous avons déjà vu plus haut (Titre Chapitre 2) le moyen d’insérer des liens hypertextes référant à des sections du même document (ancres).

`A ReStructuredText Primer <http://docutils.sourceforge.net/docs/user/rst/quickstart.html>`_

`A ReStructuredText Primer`_ (hyperlien)
.. _ReStructuredText Primer: http://docutils.sourceforge.net/docs/user/rst/quickstart.html (cible, indiquée plus loin dans le document, ou à sa toute fin)

Substitutions¶

Il est possible de spécifier un ou plusieurs mots (bloc), censés revenir souvent dans un document, qui remplaceront à la compilation le terme qui les représente. Cela est utile pour représenter des mots, une image (mais pas des liens hypertextes). Voici comment représenter le bloc et le mot qui les représente:

Voici un |mot| à remplacer.

et comment on indique le bloc qui va remplacer le mot (à placer n’importe où dans le doc, p. ex. en toute fin):

.. |mot| `mot qui va remplacer celui`

Cela sera rendu ainsi :

Voici un mot qui va remplacer celui à remplacer.

Il existe également les termes réservés suivants : |today|, qui insère la date courante ; `` 1.0 et |release] qui indiquent resp. les numéros de la version et de la sous-version du projet.

Directives¶

Passons maintenant à la description de directives, qui étendent les capacités de reST. Il est à noter qu’on ne peut utiliser de directives avec du texte mis en forme (gras, italiques).

     .. raw:: html

<hr width=50 size=10>

.. contents:: Table des matières
        :depth: 2
        :local:
        :backlinks: top

Images¶

Pour inclure une image dans votre document, utiliser la directive image. Par exemple :: .. image:: images/computer.png sera rendu ainsi :

Il est possible d’ajouter des informations de taille, d’échelle, d’alignement et de texte alternatif

.. image:: images/computer.png
        :height: 100
        :width: 200
        :scale: 50
        :align: center
        :alt: ordinateur

Sera rendu ainsi :

.. sidebar:: Titre du texte flottant
        :subtitle: Texte optionnel

        Le texte flottant est ici.

Formules mathématiques¶

Il est possible d’insérer, dans le texte ou en tant que bloc spécifique, des formules mathématiques (utiliser la syntaxe LaTeX). Voici le bloc:

.. math::

        α_t(i) = P(O_1, O_2, … O_t, q_t = S_i λ)

qui sera rendu :

et les formules dans le texte : :math:`A_\text{c} = (\pi/4) d^2, sera rendu ainsi : \(A_\text{c} = (\pi/4) d^2\).

Directives HTML¶

Il existe une série de directives spécifiques HTML permettant d’ajouter des méta-données ou des balises HTML dans un document reST. La directive .. meta:: permet d’ajouter des méta-données dans le document (balise meta).

Et après ?¶

Ce document est une simple introduction à reST. Plus d’informations ici :

• Intro à reST en français (AFUL)
• Quick reST
• L’ensemble des directives