Démarrer avec Sphinx¶
Sphinx est un générateur de documentation entendu comme un outil transformant un ensemble de fichiers texte source en différents formats de sortie , en produisant automatiquement les références croisées, index, etc. Ainsi, si vous disposez d’un répertoire contenant un groupe de documents reStructuredText ou Markdown, Sphinx peut générer une série de fichiers HTML, un fichier PDF (via LaTeX), des pages de manuel et plus encore.
Sphinx se focalise sur la documentation, en particulier la documentation manuscrite, cependant, Sphinx peut aussi être utilisé pour générer des blogs, des sites Internet et même des livres. Une grande partie de la puissance de Sphinx lui vient de la richesse de son format de balisage en texte brut par défaut reStructuredText, accompagné de ses capacités d’extension significatives.
The goal of this document is to give you a quick taste of what Sphinx is and how you might use it. When you’re done here, you can check out the installation guide followed by the intro to the default markup format used by Sphinx, reStructuredText.
Pour une excellente « introduction » à l’écriture de documentation en général – les pourquoi et comment, voir également Write the docs, écrit par Eric Holscher.
Configurer les sources¶
Le répertoire racine d’une collection Sphinx de sources de documents en texte brut est appelé répertoire source. Ce répertoire contient également le fichier de configuration conf.py de Sphinx, dans lequel vous pouvez paramétrer tous les aspects de la façon dont Sphinx lit vos sources et construit votre documentation. [1]
Sphinx fournit un script appelé sphinx-quickstart créant un répertoire source et un fichier conf.py par défaut avec les paramètres essentiels configurés à partir de quelques questions qu’il vous pose. Pour l’utiliser, exécutez :
$ sphinx-quickstart
Définir la structure¶
Présumons que vous avez exécuté sphinx-quickstart. Celui-ci a créé un répertoire source contenant le fichier conf.py et un document racine index.rst. La fonction principale du root document est de servir de page de bienvenue, et de contenir la racine de « l’arbre de la table des matières » (ou toctree). C’est l’une des principales fonctions que Sphinx ajoute à reStructuredText, une manière de relier plusieurs fichiers dans une hiérarchie unique de documents.
Directives reStructuredText
toctree est une directive reStructuredText, un type de balise très polyvalent. Les directives peuvent recevoir des arguments, avoir des options et un contenu.
Les arguments sont passés directement après les doubles deux points suivant le nom de la directive. Chaque directive définit si elle peut recevoir des arguments, et combien.
Les options sont définies après les arguments, sous la forme d’une « liste de champs ». maxdepth est un exemple d’une telle option pour la directive toctree.
Le contenu suit les options ou les arguments, séparé d’une ligne blanche. Chaque directive définit si elle accepte du contenu, et qu’en faire.
Un piège courant avec les directives est que la première ligne du contenu doit être indentée au même niveau que le sont les options.
La directive toctree est initialement vide et se présente comme ceci :
.. toctree::
:maxdepth: 2
Les documents y sont ajoutés en les listant dans le contenu de la directive :
.. toctree::
:maxdepth: 2
usage/installation
usage/quickstart
...
Voici exactement comment se présente la toctree de la présente documentation. Les documents à inclure sont listés par leurs nom du document, c’est à dire sans l’extension du nom de fichier et en utilisant des slash (« / ») comme séparateurs de répertoires.
Voir aussi
Read more about the toctree directive.
Vous pouvez maintenant créer les fichiers listés dans la toctree et y ajouter du contenu, les titres de leurs sections seront insérés (jusqu’au niveau maxdepth) à l’endroit où la directive toctree est placée. En outre, Sphinx connait dès lors l’ordre et la hiérarchie de vos documents. (Ceux-ci peuvent eux-mêmes contenir des directives toctree, ce qui signifie que vous pouvez si nécessaire créer des hiérarchies profondément imbriquées.)
Ajouter du contenu¶
La plupart des fonctionnalités standard de reStructuredText peuvent être utilisées dans les fichiers source Sphinx. D’autres sont également ajoutées par Sphinx. Par exemple, des références croisées peuvent être créées de façon portable (fonctionnant quelque soit le type de sortie) en utilisant le rôle ref.
Pour un exemple, si vous lisez la version HTML de ce document, vous pouvez regarder la source de celui-ci – utilisez le lien « Affichez la source » dans la barre latérale.
Voir aussi
reStructuredText for a more in-depth introduction to reStructuredText, including markup added by Sphinx.
Générer la documentation¶
Maintenant que vous avez ajouté des fichiers et du contenu, générons une première version de la documentation. La génération est lancée en utilisant le programme sphinx-build :
$ sphinx-build -M html sourcedir outputdir
where sourcedir is the source directory, and outputdir is the
directory in which you want to place the built documentation.
The -M option selects a builder; in this example
Sphinx will build HTML files.
Voir aussi
Refer to the sphinx-build man page for all options that sphinx-build supports.
You can also build a live version of the documentation that you can preview in the browser. It will detect changes and reload the page any time you make edits. To do so, use sphinx-autobuild to run the following command:
$ sphinx-autobuild source-dir output-dir
Toutefois, le script sphinx-quickstart crée des fichiers Makefile et make.bat vous rendant la vie encore plus facile. Ceux-ci peuvent être lancés en exécutant la commande make avec le nom du générateur. Par example :
$ make html
Ceci générera la documentation HTML dans le répertoire de destination choisi. Exécutez la commande make sans argument pour obtenir la liste des cibles disponibles.
Comment générer des documents PDF ?
make latexpdf exécute le générateur LaTeX et facilite l’utilisation de la chaîne de compilation pdfTeX.
Documenter des objets¶
Un des principaux objectifs de Sphinx est de faciliter la documentation d”objects (au sens très large) dans n’importe quel domaine. Un domaine est une collection d’objets allant de pair, et un balisage permettant la création et le référencement de ces objets.
Le domaine majeur est le domaine Python. Par exemple, pour documenter la fonction intégrée enumerate(), vous ajouteriez les lignes ci-dessous à vos fichiers source:
.. py:function:: enumerate(sequence[, start=0])
Return an iterator that yields tuples of an index and an item of the
*sequence*. (And so on.)
Ce qui serait rendu de la façon suivante :
- enumerate(sequence[, start=0])¶
Renvoie un itérateur qui produit des n-uplets avec un indice et un élément de la séquence. (Et ainsi de suite.)
L’argument de la directive est la signature de l’objet décrit, le contenu est la documentation de celui-ci. Des signatures multiples peuvent être passées, chacune sur sa propre ligne.
Le domaine Python se trouvant également être le domaine par défaut, le préfixe du nom du domaine peut être omis :
.. function:: enumerate(sequence[, start=0])
...
produit le même rendu que précédemment si le paramètre de domaine par défaut reste inchangé.
Il existe plusieurs autres directives pour documenter les autres types d’objets Python, par example py:class ou py:method. Il existe également un rôle de référencement croisé pour chacun de ces types d’objet. Ce balisage créera un lien vers la documentation de enumerate()`.
The :py:func:`enumerate` function can be used for ...
En voici la preuve: un lien vers enumerate().
À nouveau, le préfixe py: peut être omis si le domaine Python est resté celui par défaut. Peu importe quel fichier contient effectivement la documentation de enumerate(); Sphinx la trouvera et créera un lien vers celle-ci.
Chaque domaine a ses règles de syntaxe pour les signatures, embellit le formatage des sorties, ou ajoute des fonctionnalités supplémentaires comme des liens vers des types de paramètres, par exemple dans le domaine C/C++.
Voir aussi
Domains for all the available domains and their directives/roles.
Configuration de base¶
Plus tôt, nous avons mentionné que le fichier conf.py contrôlait la façon dont Sphinx traitait vos documents. Dans ce fichier, exécuté comme un fichier source Python, vous affectez des valeurs de configuration. Pour les utilisateurs avancés, puisque le fichier est exécuté par Sphinx, il est possible d’y réaliser des tâches complexes, comme étendre sys.path ou importer un module pour en identifier la version documentée.
Les valeurs de configuration que vous seriez susceptible de vouloir changer sont pré-insérées dans le fichier conf.py par sphinx-quickstart et initialement mises en commentaire (avec la syntaxe Python standard: un # mets en commentaire le reste de la ligne). Pour changer une valeur par défaut, supprimez le signe dièze et modifiez la valeur. Pour personnaliser un paramètre de configuration qui n’est pas ajouté automatiquement par sphinx-quickstart, ajouté simplement une nouvelle affectation.
Gardez en tête que le fichier utilise la syntaxe Python pour les chaines, nombres, listes, etc. Le fichier est enregistré en UTF-8 par défaut, tel qu’indiqué par la déclaration d’encodage à la première ligne.
Voir aussi
Configuration for documentation of all available config values.
Autodoc¶
Pour la documentation de code Python, il est commun de placer beaucoup de celle-ci dans les fichiers source même, dans des chaines de documentation. Sphinx supporte l’inclusion des docstrings dans vos modules grâce à une extension (une extension est un module Python fournissant des fonctionnalités supplémentaires pour les projets Sphinx) appelée autodoc.
Voir aussi
sphinx.ext.autodoc
for the complete description of the features of autodoc.
Intersphinx¶
Beaucoup de documents Sphinx, y compris la Python documentation sont publiés sur Internet. Lorsque vous souhaitez créer des liens vers de tels documents depuis votre documentation, vous pouvez le faire avec sphinx.ext.intersphinx.
Afin d’utiliser intersphinx, il vous faut d’abord l’activer dans conf.py en ajoutant la chaîne 'sphinx.ext.intersphinx' à la liste extensions et configurer la valeur du paramètre intersphinx_mapping.
Par exemple, pour créer un lien vers io.open() dans le manuel de la bibliothèque Python, vous devez configurer intersphinx_mapping de la façon suivante :
intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
Dès lors, vous pouvez écrire une référence croisée :py:func:`io.open`. Toute référence croisée qui n’a pas de cible correspondante dans le jeu de documentation courant sera recherchée dans les documentations configurées dans intersphinx_mapping (ce qui nécessite un accès à l’URL configurée pour télécharger la liste des cibles valides). Intersphinx fonctionne également avec d’autres rôles de domaine y compris :ref:, cependant il ne fonctionne pas pour :doc: car ce n’est pas un rôle de domaine.
Voir aussi
sphinx.ext.intersphinx
for the complete description of the features of intersphinx.
Pour aller plus loin¶
Fichiers statiques
Utiliser des extensions
Notes de bas de page