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.
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 de document, c’est à dire sans l’extension du nom de fichier et en utilisant des slash (« / ») comme séparateurs de répertoires.
En savoir plus à propos de la directive toctree
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.
À faire
Mettre à jour le lien ci-dessous lorsque de nouveaux guides seront ajoutés sur ceux-ci.
Voir reStructuredText pour une introduction approfondie à reStructuredText, incluant les balises ajoutées par 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.
Référez-vous à la page de manuel de sphinx-build pour toutes les options supportées par le sphinx-build.
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
À faire
Déplacer l’ensemble de cette section dans un guide sur rST ou les directives.
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++.
See 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 Configuration pour la documentation de l’ensemble des paramètres de configuration disponibles.
À faire
Déplacer l’ensemble de cette documentation vers une autre section.
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.
Pour utiliser autodoc, vous devez l’activer dans le fichier conf.py en ajoutant la chaîne 'sphinx.ext.autodoc' à la liste affectée au paramètre de configuration extensions :
extensions = ['sphinx.ext.autodoc']
Dès lors, quelques directives supplémentaires sont à votre disposition. Par exemple, pour documenter la fonction io.open(), en lisant sa signature et sa docstring depuis le fichier source, vous écririez ceci :
.. autofunction:: io.open
Vous pouvez également documenter des classes entières et même des modules automatiquement en utilisant les options member des directives auto*, comme dans :
.. automodule:: io
:members:
autodoc a besoin d’importer vos modules pour en extraire les docstrings. Par conséquent, il faut ajouter le chemin approprié au paramètre sys.path dans votre fichier conf.py.
Avertissement
autodoc importe les modules à documenter. Si des modules ont des effets de bord à l’importation, ils seront exécutés par autodoc quand sphinx-build est exécuté.
Si vous documentez des scripts (par opposition aux modules de bibliothèque), assurez-vous que leur routine principale est protégée par une condition if __name__ =='__main__'.
Voir sphinx.ext.autodoc pour une description complète des fonctionnalités d’autodoc.
À faire
Déplacer cette documentation vers une autre section.
Intersphinx¶
Beaucoup de documents Sphinx, y compris la documentation Python 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 sphinx.ext.intersphinx pour une description complète des fonctionnalités d’intersphinx.
Pour aller plus loin¶
Fichiers statiques
Utiliser des extensions
Notes de bas de page