Documentation narrative dans Sphinx¶
Structurer votre documentation sur plusieurs pages¶
Le fichier index.rst créé par sphinx-quickstart est le document racine, dont la fonction essentielle est de servir de page d’accueil et decontenir la racine de « l’arborescence de la table des matières » (ou toctree). Sphinx vous permet d’assembler votre projet à partir de différents fichiers, ce qui s’avère utile lorsque le projet grandit.
À titre d’exemple, créez un fichier docs/source/usage.rst (à côté de index.rst) avec le contenu suivant :
Usage
=====
Installation
------------
To use Lumache, first install it using pip:
.. code-block:: console
(.venv) $ pip install lumache
Ce fichier contient deux titres de section, un paragraphe de texte normal, et une directive code-block qui restitue un bloc de contenu sous la forme de code source, avec la coloration syntaxique appropriée (dans ce cas, texte de console générique).
La structure du document est déterminée par la succession de styles de titres, ce qui signifie que, en utilisant ---` pour la section « Installation » après === pour la section « Usage », vous avez déclaré que « Installation » était une sous-section de « Usage ».
Pour compléter la procédure, ajoutez une directive toctree à la fin du fichier index.rst en y incluant le document juste créé, comme suit :
Contents
--------
.. toctree::
usage
Cette étape insère le document à la racine de la toctree, qui fait désormais parti de la structure de votre projet, qui à ce stade se présente comme ceci :
index
└── usage
Si vous générez la documentation HTML en exécutant make html, vous verrez que toctree est rendu comme une liste d’hyperliens, ce qui vous permet de naviguer vers la page nouvellement créée. Propre !
Avertissement
Les documents en dehors de la toctree provoquerons un message WARNING: Le document n'est inclus dans aucune toctree. pendant le processus de génération, et sera inaccessibles pour le lecteur.
Ajouter des références croisées¶
Une des puissantes fonctionnalités de Sphinx est la possibilité d’ajouter facilement des références croisées vers des éléments spécifiques de la documentation : un document, une section, une illustration, un objet code, etc. Le tutoriel en est plein !
Pour ajouter une référence croisée, ajoutez cette phrase juste après le paragraphe d’introduction dans index.rst :
Check out the :doc:`usage` section for further information.
Le rôle <rst-roles-alt>` doc utilisé référence automatiquement un document spécifique dans le projet, dans ce cas le fichier usage.rst créé précédemment.
Par ailleurs, vous pouvez aussi ajouter une référence croisée vers une partie quelconque du projet. Pour cela, vous devez utiliser le rôle ref, et ajouter une étiquette faisant office de cible.
Par exemple, pour référencer la sous-section « Installation », ajoutez une étiquette juste avant le titre, comme suit :
Usage
=====
.. _installation:
Installation
------------
...
Et modifiez la phrase ajoutée au fichier index.rst comme ceci :
Check out the :doc:`usage` section for further information, including how to
:ref:`install <installation>` the project.
Notez une astuce ici : la partie install précise la façon dont apparaîtra le lien (nous voulons un texte précis, afin que la phrase ait un sens), alors que la partie <installation> renvoie véritablement à l’étiquette vers laquelle nous voulons ajouter une référence croisée. Si vous n’incluez pas un titre explicitement, utilisant donc :ref:installation, le titre de la section sera utilisé par défaut (dans ce cas, « Installation »). Les rôles :doc: et :ref: seront tous deux rendus comme des hyperliens dans la documentation HTML.
Qu’en est-il de la documentation d’objets de code dans Sphinx ? Lisez la suite !