Les bases de la syntaxe de Sphinx¶

Marquage sémantique¶

Les rôles ci-dessous permettent un formatage spécifique du texte.

• :abbr:`OVNI (Objet volant non identifié)` est rendu ainsi : OVNI. En output HTML, cela affiche une infobulle avec la traduction lors du survol du mot avec la souris.
• :command:`ls -al` affiche une commande d’un système d’exploitation et est rendu ainsi : ls -al.
• :file:`/usr/lib/python2/zut.py` affiche un nom de fichier ou de répertoire et est rendu ainsi : /usr/lib/python2/zut.py

Références vers des sections¶

reST permet créer un lien hypertexte d’un endroit à l’autre d’un même document (voir Titre Chapitre 2). Sphinx ajoute des rôles permettant de créer des références croisées dans un projet donné, du moment que les étiquettes créées sont bien uniques. On peut placer une étiquette (arbitraire mais unique) juste avant un titre de section (quel que soit son niveau). Par exemple l’ajout de .. _ref_sections au titre la section courante (voir la source de ce document) permettra d’insérer un lien hypertexte vers le titre de cette section ainsi :::ref:`ref_sections`, ce qui donnera Marquage sémantique.

Dans ce cas, le titre utilisé dans le lien est celui du titre vers lequel il pointe. Il est aussi possible de spécifier un titre particulier en spécifiant :ref:Titre spécifique <ref_sections>, qui référera également à Titre spécifique.

Ce type de lien avec le rôle :ref: fonctionne également avec les directives .. figure:::

.. _ma_figure:

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

   Un ordinateur

rendue ainsi :

Fig. 1 Un ordinateur

Il est également possible de pointer, avec le rôle :numref:, vers une Figure donnée avec un lien hypertexte affichant un numéro de figure. Par exemple, on pointera vers la Figure précédente ainsi : :numref:`Un ordinateur (Fig. %s) <ma_figure>`, ce qui sera rendu ainsi : Un ordinateur (Fig. 1). Attention, cela nécessite d’ajouter dans le fichier conf.py (section “General configuration”) les deux lignes suivantes (permettant de numéroter les Fig, Tab. et blocs de code), voir https://github.com/sphinx-doc/sphinx/issues/1763:

numfig = True
numfig_format = {'figure': 'Fig. %s', 'table': 'Tab. %s', 'code-block': 'Code %s'}

Références vers des documents¶

Il est également possible de créer des liens hypertextes vers des documents, avec le rôle :doc:. ainsi, :doc:`syntaxe_rest` créera un lien hypertexte vers le document ciblé : Les bases de reStructuredText.

Liens hypertextes vers des fichiers à télécharger¶

Enfin, il est possible de pointer vers des fichiers non reST (p. ex., des PDF, des images à télécharger), placés dans un dossier ad hoc au sein de l’arborescence du projet, avec le rôle :download:. Lorsque ce rôle est utilisé, le fichier concerné est automatiquement recopié dans l’output, lorsque cela est possible (si du HTML est généré), dans le répertoire _downloads. Par exemple :download:`Téléchargez cette image <images/computer.png>` sera rendu ainsi Téléchargez cette image.

Admonitions¶

Se référer à Paragraphes spécifiques (admonitions) pour les admonitions reST. Les directives .. note::, .. warning::, et .. seealso::. Cette dernière doit contenir une liste de définitions (voir liste_definition).

Elles sont rendues respectivement ainsi :

Indications d’auteurs¶

La directive .. sectionauthor:: indique l’auteur et le courriel de l’auteur de la section en cours. Cette indication ne s’affiche pas par défaut dans l’output (elle peut servir aux auteurs du document), mais si on met la variable show_author à True, elle s’affiche:

.. sectionauthor:: Guido van Rossum <guido@python.org>

sera rendu ainsi :

Indications de versions¶

Sphinx étant au départ conçu pour documenter Python, un langage de programmation, il existe différentes indications permettant de documenter des numéros de version. Cela peut aussi s’utiliser, bien sûr, pour documenter les changements d’un document. L’indication varie en fonction de la langue définie dans le fichier conf.py. Les commandes .. versionadded:: et .. versionchanged:: signalent ce qui a été ajouté ou changé dans la version actuelle du document

.. versionadded:: 2.5
        le paramètre *spam*. Noter qu'il n'y a pas de ligne vide entre l'intitulé de la version et l'explication, pour faciliter la lecture.

est rendu ainsi :

et:

.. versionchanged:: 2.5
        le paramètre *spam*. Noter qu'il n'y a pas de ligne vide entre l'intitulé de la version et l'explication, pour faciliter la lecture.

est rendu ainsi :

Titre non indexé¶

La directive .. rubric:: crée un titre qui n’est pas indexé dans la table des matières. Comme ce qui suit :

title

Liste multicolonnes¶

La directive .. hlist:: affiche une liste dans un format plus compact, soit multicolonnes, soit avec un espacement moins important (cela dépend du builder). Une option :columns: permet de spécifier le nombre de colonnes (défaut : 2):

.. hlist::
   :columns: 3

   * Une liste de
   * courts items
   * qui sont
   * affichés
   * horizontalement

est rendu ainsi :

Montrer du code¶

Plus d’informations ici.

Comme déjà dit, Sphinx est à son origine un logiciel de documentation de langage informatique. Il est donc possible d’insérer et de commenter du code ainsi. La directive .. code-block:: permet de spécifier le langage et d’afficher des blocs de code:

.. code-block:: python

    def fib(n):
      a, b = 0, 1
         while a < n:
         print(a, end=' ')
         a, b = b, a+b
         print()

sera rendu ainsi (noter la mise en forme des commandes Python) :

def fib(n):
   a, b = 0, 1
      while a < n:
      print(a, end=' ')
      a, b = b, a+b
      print()

Comme notre but est plutôt de documenter les fonctionnalités de Sphinx pour ses utilisations académiques, nous n’irons pas plus loin dans le détail de ces fonctionnalités.

La directive toctree¶

Cette directive insère une table des matières où elle est spécifiée, se servant des noms de fichiers inscrits dans le corps de la directive. Les noms de fichiers relatifs (ne commençant pas par un slash) sont relatifs au document dans laquelle la directive est spécifiée. Les noms de fichiers absolus sont relatifs au répertoire source. Une option maxdepth peut être spécifiée pour indiquer la profondeur en niveaux de la table des matières (par défaut : tous les niveaux sont inclus). Un fichier index devrait contenir une telle directive pour donner une table des matières générale du projet.

Voici un exemple:

.. toctree::
   :maxdepth: 2

  syntaxe_rest

qui est rendu ainsi :

Voici comment Sphinx opère :

• Une table des matières incluant tous les documents spécifiés dans le corps de la directive sont insérés, avec un niveau maximal de 2. Les directives toctree inclues dans ces documents sont aussi prises en compte.
• Sphinx détermine que ces fichiers sont des “fils” du document dans lequel la directive est placée. L’ordre des documents spécifiés dans le corps de la directive est utilisé pour générer des liens hypertexte “chapitre précédent”, “chapitre suivant” et “chapitre parent”, permettant de naviguer dans la hiérarchie des fichiers.

Entrées¶

Sphinx récupère automatiquement les titres des documents référencés dans le corps de la directive pour produire la table des matières. Si ce n’est pas cela qui est voulu, il est possible de spécifier un titre explicite et une cible en utilisant la syntaxe reST des liens hypertextes (et la syntaxe Sphinx des références croisées). Il est aussi possible d’ajouter des liens hypertextes vers des URL externes au projet.

Voici ce que cela donne. Cette ligne référera au document syntaxe_rest tout en utilisant le titre principale “Tout ce qui concerne la syntaxe de reST”, à la place du titre réel du document “syntaxe_reST” (cela peut être utilisé pour avoir des titres plus courts ou au contraire plus explicites dans la table des matières générale):

.. toctree::

   Tout ce qui concerne la syntaxe de reST <syntaxe_rest>

Ce sera rendu ainsi :

Options additionnelles¶

La directive .. toctree:: a les options suivantes.

• l’option :numbered: peut être ajoutée. Les sous-tables des matières sont automatiquement numérotées, et ce dans tout le document.
• l’option :caption: permet de spécifier spécifier un titre particulier,
• l’option :name: permet de spécifier un nom-cible à utiliser dans des liens hypertextes avec :ref:.
• l’option :titlesonly: permet de ne spécifier que les titres de niveau 1.

Ajouter du contenu selon des tags¶

La directive .. only:: <expression> permet d’ajouter un contenu (bloc de texte) seulement si l’expression est vraie. L’expression est composée d’un ou des tags (étiquettes) tels que .. only:: html and draft. Des tags non définis dans un quelconque document du projet sont évalués comme faux. Des tags définis dans un document (via l’option -t ou dans le fichier conf.py) sont vrais. Des expressions booléennes (html and (latex or draft)) sont permises. Le format et le nom des différents builders (html, latex, text) sont toujours déclarés comme tags.

Il est à noter que c’est une commande d’ajout : l’ensemble des documents non taggés sont produits en output quand on spécifie une étiquette donnée.

Par exemple, le bloc suivant:

.. only:: master_2

   Ce texte ne s'affichera que lors de la compilation (build) précisant le tag Master_2 (ajouter -t master_2 au début de la commande build). L'ensemble des documents non taggés sera affiché.