Impression
| author: | William Dode |
|---|---|
| Contact: | wilk at flibuste.net |
| Copyright: | Ce texte est placé dans le domaine public. |
Ce texte décrit les directives d'un point de vue auteur (et non informaticien). Il est adapté du texte de David Goodger reStructuredText Directives1
Les termes anglais originaux sont décrits entre parenthèses, on peut employer l'un ou l'autre. En revanche les paramètres et options doivent être indiqués en anglais, pour le moment.
Les directives sont indiquées de cette manière:
.. nom de la directive:: premier paramètre (facultatif ou non suivant la directive)
:option: contenu d'une option (toujours facultative)
<--- ligne vide --->
Texte de la directive (facultatif ou non suivant la directive)
Attention!
Laisser un espace entre .. et le nom de la directive, mais pas entre le nom de la directive et ::
Décaler correctement le texte et les options avec des espaces à gauche
Laisser une ligne vide entre .. nom de la directive:: et le texte
Pour indiquer un paramètre vide (pas de titre alors qu'il est obligatoire), il suffit de taper
par exemple:
.. sommaire:: \
Les admonitions contiennent un titre et un texte. Le rendu est généralement encadré.
Les différentes admonitions sont :
Exemple:
.. attention::
Ceci est un message d'alerte
Il est possible d'utiliser une admonition générique en indiquant en paramètre le titre de l'admonition
.. admonition:: titre de l'admonition
Texte de l'admonition
La directive image permet d'intégrer une image au milieu d'un document en indiquant son chemin d'accès:
.. image:: chemin de l'image (/images/img.jpg par ex)
:height: taille verticale
:width: taille horizontale
:scale: échelle
:alt: texte à afficher si le navigateur ne peut pas afficher les images (utile pour les aveugles par ex.)
:align: alignement ("top" en haut , "middle" au milieu, "bottom" en bas, "left" à gauche, "center" au centre, ou "right" à droite)
:class: classe de l'image
:target: url en cas de clic sur l'image
Il est possible d'utiliser certains paramètres :
Une figure est une image (avec toutes ses options) avec quelques options supplémentaires, un sous-titre et une légende):
.. figure:: chemin de l'image
:figwidth: largeur du cadre contenant les légendes et l'image
:figclass: classe de la figure
Sous-titre de la figure
Légende de la figure, éventuellement
sur plusieurs lignes et paragraphes.
Ce qui donne :
+---------------------------+ | figure | | | |<------ figwidth --------->| | | | +---------------------+ | | | image | | | | | | | |<--- width -------- >| | | +---------------------+ | | | |Le texte devrait rester | |à l'intérieur du cadre | +---------------------------+
Section à part, parfois encadrée:
.. sujet:: titre du sujet (impératif)
:class: définition de la classe
texte...
titre du sujet (impératif)
texte...
Texte encadré:
.. encadré:: titre de l'encadré (impératif) :subtitle: sous-titre :class: définition de la classe texte
Bloc de texte dont la mise en forme ne sera pas modifiée (utile pour les poèmes par exemple):
.. bloc-textuel::
:class: définition de la classe
la
mise
en
forme
sera
conservée
Comportement identique à un Bloc-textuel (line-block) dont le rendu sera légèrement différent (souvent utilisé pour montrer du code de programme)
Définit une section/rubrique qui ne fait pas partie de la structure du document et ne rentrera pas dans le sommaire:
.. intertitre:: titre de l'intertitre (impératif)
titre de l'intertitre (impératif)
Épigraphe, généralement en tête de document (mais pas obligatoirement), avec une éventuelle attribution:
.. épigraphe:: texte de l'épigraphe -- attribution facultative (précédé impérativement de --)
texte de l'épigraphe
attribution facultative (précédé impérativement de --)
Chapeau, généralement en tête de document (mais pas obligatoirement):
.. chapeau:: texte du chapeau -- attribution facultative
texte du chapeau
attribution facultative
Accroche, généralement un extrait du texte:
.. accroche:: texte de l'accroche -- attribution facultative
texte de l'accroche
attribution facultative
Permet d'afficher le sommaire du document avec un titre facultatif et une profondeur paramétrable:
.. sommaire:: titre facultatif
:depth: profondeur
:local: uniquement sur les sous-section de la section en cours
:backlinks: "entry", "top", "none" génère un lien des sections vers la section dans le sommaire,
des sections vers le sommaire ou aucun lien.
Permet de numéroter automatiquement les sections de tout le document:
.. sectnum:: :depth: profondeur maximale
Affiche la liste de tous les liens externes du type:
`lien`_ .. _`lien`: url du lien externe
| [1] | http://docutils.sourceforge.net/spec/rst/directives.html |
Pour inclure un texte (reStructuredText ou texte brut):
.. inclure:: chemin d'accès au fichier :literal: pour ne pas analyser la structure du texte (si ce n'est pas un texte *rst*)
En fin de document le source de ce document est inséré de cette manière
Permet d'insérer du texte brut (html ou latex) qui ne sera pas analysé par rst:
.. brut:: html :file: chemin d'accès d'un fichier html à inclure :url: url d'un document html à inclure <b> texte html balisé </b><br/>texte html balisé
De la même manière avec latex:
.. brut:: latex
:file: chemin d'accès d'un fichier latex à inclure
\textbf{texte latex balisé}
Permet de remplacer automatiquement un texte, souvent utilisé pour des abréviations:
tout le texte entre des barres (|rst| par exemple) va être remplacé par reStructuredText .. |rst| remplacer:: reStructuredText
tout le texte entre des barres (reStructuredText par exemple) va être remplacé par reStructuredText
La fameuse option class que l'on retrouve dans quelques directives va servir à personnaliser la présentation de la directive
Si elle n'est pas gérée par la feuille de style elle sera simplement ignorée.
Pour affecter une classe à un bloc de texte hors directive:
.. class:: special Ceci est un paragraphe spécial .. class:: exceptionnel Une section exceptionnelle ========================== Un paragraphe ordinaire
Ceci est un paragraphe spécial
Un paragraphe ordinaire
Pour affecter une classe à un bloc décalé il faut faire suivre la directive par un commentaire vide:
.. classe:: special .. bloc de texte spécial décalé
bloc de texte spécial décalé
Attention!
L'option class doit être écrite en anglais pour l'instant, contrairement à la directive qui peut être écrite dans les deux langues.