Les bases de la syntaxe de Sphinx#

Information

Auteurs : Ce document est la documentation principale de Sphinx, traduite par Philippe Dessus, Inspé & LaRAC, Univ. Grenoble Alpes.
Date de création : Juillet 2016.
Résumé : Ce document donne les principaux éléments de la syntaxe Sphinx.
Voir aussi : Il est préférable de commencer par lire le Document syntaxe_rest avant celui-ci.

Introduction#

Nous décrivons ici les principaux éléments de syntaxe de Sphinx. Il faut comprendre que Sphinx est une extension du langage de description reStructuredText, et qu’il sera donc nécessaire au lecteur de parcourir le document syntaxe_rest pour en avoir une idée suffisante. Sphinx étend donc les fonctionnalités de reST par un ensemble de directives, principalement liées à l’organisation et au référencement (liens, glossaire, table des matières) des documents d’un projet.

Il faut aussi noter que le respect des indentations de paragraphes après une directive sont indispensables : Sphinx s’en sert pour détecter ce qui va être affiché (corps).

Balises au niveau du texte#

Plus d’informations ici.

Marquage sémantique#

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

Références vers des sections#

reST permet créer un lien hypertexte d’un endroit à l’autre d’un même document (voir lien_interne). 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 ref_sections.

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 :

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. %s). 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 sphinx-doc/sphinx#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 d’un même projet, avec le rôle :doc:. Ainsi, :doc:`syntaxe_rest` créera un lien hypertexte vers le document ciblé : Les bases de reStructuredText (pointant au début du document). Si l’on veut pointer sur un endroit particulier du document, utiliser une ancre et le rôle :ref: (voir lien_interne). Dans le cas où le document appartiennent à des projets différents, il faut utiliser l’extension intersphinx (voir Références inter-projets Sphinx).

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.

Balises au niveau du paragraphe#

Plus d’informations ici

Admonitions#

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

Elles sont rendues respectivement ainsi :

Note

Voici un paragraphe que je veux mettre en évidence. Voici un paragraphe que je veux mettre en évidence. Voici un paragraphe que je veux mettre en évidence.

Avertissement

Voici un paragraphe que je veux mettre en évidence. Voici un paragraphe que je veux mettre en évidence. Voici un paragraphe que je veux mettre en évidence.

Voir aussi

Terme: Définition

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 :

Nouveau dans la version 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.

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 :

Modifié dans la version 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.

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 :

Une liste de
courts items

qui sont
affichés

horizontalement

Afficher 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.

Afficher une table des matières#

Plus d’informations ici

reST n’a pas de fonctionnalités permettant aisément de relier plusieurs documents ensemble (en projets), ou de séparer des documents en de multiples fichiers d’output, Sphinx a une directive qui spécifie des relations entre les fichiers isolés d’une documentation, ainsi que des tables des matières, la directive .. toctree::.

Tous les documents inclus dans un répertoire de projet doivent être inclus dans une directive “toctree” d’un des documents. Dans le cas contraire Sphinx indiquera une alerte après compilation, car de tels fichiers ne pourront être atteints par une navigation standard.

Si l’on veut qu’un document ne soit pas compilé, indiquer :orphan: à la première ligne du document. Ainsi, aucune alerte ne sera produite.

Sphinx utilise la variable ‘master_doc’ (dans conf.py) comme “racine” des documents à compiler, et cette variable pointe sur la table des matières générale de l’ensemble de fichiers à compiler.

Pour certains builders (comme singlehtml), on peut donc avoir plusieurs index contenant des toctree différents, et il suffira d’indiquer leur nom dans la variable ‘master_doc’ pour les compiler séparément. Attention : cela ne fonctionne pas pour les builders html, latex, ou latexpdf, qui compilent l’ensemble des fichiers du répertoire sans tenir compte de l’index indiqué dans ‘master_doc’.

Si l’on veut produire des documents de cours différents, puisés dans le même dossier, la solution la moins complexe (bien que peu élégante) est de procéder ainsi :

créer un nouveau dossier et créer des liens physiques (hard links) entre les fichiers du répertoire-source et ceux qui vont composer l’index du nouveau document. Les fichiers conf.py ou index.rst seront simplement recopiés pour permettre leur modification locale. Tous les fichiers annexes dépendant du sous-ensemble de fichiers pourront être simplement recopiés, s’ils ne doivent pas changer trop souvent.

Il est aussi à noter que la simple fusion d’un fichier dans un autre se fait avec la directive .. include::

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.

Index#

Il est aussi possible de créer un index de termes contenus dans un document, avec le rôle suivant :index:`référence` qui créera une référence à cet endroit de la table d’index, table accessible en général de la fin de fichier index).

Astuce#

Comme un dossier de documents-source peut contenir plusieurs index, pour compiler des documents différents, il suffit de modifier le nom du fichier index dans le fichier conf.py pour compiler le document voulu.

Glossaire#

Plus d’informations ici

Il existe une directive .. glossary::, qui doit contenir dans son corps une liste de définition (voir Les listes de définition). L’option :sorted: affiche le glossaire par ordre alphabétique:

.. glossary::
  :sorted:

       Projet Sphinx
              Un projet Sphinx est un ensemble de documents à propos d'un thème donné, réunis et ordonnancés par un fichier index.

Ce qui est rendu ainsi :

Projet Sphinx#
: Un projet Sphinx est un ensemble de documents à propos d’un thème donné, réunis et ordonnancés par un fichier index.#

La référence à un glossaire se réalise avec le rôle :term:, ainsi (la casse n’est pas prise en compte):

:term:`builder`

ce qui est rendu ainsi : builder

Balisage additionnel#

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é.

On peut utiliser aussi la directive only pour générer des documents différents selon leur format de sortie. Par exemple, faire précéder de la directive:

.. only:: builder_html or builder_singlehtml

un bloc ne l’affichera que pour les sorties HTML ou SingleHTML. Cela est par exemple indispensable lorsqu’on a des documents comprenant des extensions spécifiques (p. ex. ReAuthoring), ne s’affichant que dans des sorties HTML et bloquant la compilation d’autres sorties, comme LaTeX.

Références inter-projets Sphinx#

Il peut être utile de faire des références, des liens hypertextes de renvois, entre plusieurs projets Sphinx. Il est nécessaire, auparavant, de déclarer l’extension intersphinx:

ajouter la ligne ‘sphinx.ext.intersphinx’, dans les extensions des fichiers conf.py des différents projets à inter-référencer ;
ajouter des informations sur le “mapping“, c’est-à-dire, ajouter dans le fichier conf.py de chaque projet des informations sur l’URL des fichiers build, par exemple, ce qui suit indique que la racine du projet ‘gene’ est accessible à l’URL indiquée. Bien sûr, on ajoutera les URL des différents projets, avec leur nom de référence

intersphinx_mapping = {: ‘ens-sup’: (‘http://espe-rtd-reflexpro.u-ga.fr/docs/sciedu-ens-sup/fr/latest/”,”http://espe-rtd-reflexpro.u-ga.fr/docs/sciedu-ens-sup/fr/latest/objects.inv’)

}

pour faire une référence à l’un des fichiers (ou une ancre), il suffit d’écrire à l’endroit voulu la directive suivante (qui va créer le lien hypertexte vers le document concerné) ; on peut aussi spécifier un titre

Ressources de cours en sciences de l’éducation titre

Les bases de la syntaxe de Sphinx

Contenu

Les bases de la syntaxe de Sphinx#

Introduction#

Balises au niveau du texte#

Marquage sémantique#

Références vers des sections#

Références vers des documents#

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

Balises au niveau du paragraphe#

Admonitions#

Indications d’auteurs#

Indications de versions#

Titre non indexé#

Liste multicolonnes#

Afficher du code#

Afficher une table des matières#

La directive toctree#

Entrées#

Options additionnelles#

Index#

Astuce#

Glossaire#

Balisage additionnel#

Ajouter du contenu selon des tags#

Références inter-projets Sphinx#