Extensions¶
Comme de nombreux projets auront besoin de caractéristiques spéciales dans leur documentation, Sphinx permet d’ajouter des « extensions » au processus de construction, chacune pouvant modifier presque tous les aspects du traitement des documents.
This chapter describes the extensions bundled with Sphinx. For the API documentation on writing your own extension, refer to Sphinx Extensions API.
Built-in extensions¶
Ces extensions sont intégrées et peuvent être activées par des entrées respectives dans la valeur de configuration :confval:`extensions” :
sphinx.ext.autodoc
– Inclure la documentation des chaînes docstringssphinx.ext.autosectionlabel
– Autoriser les références automatiques aux sections par leurs titressphinx.ext.autosummary
– Generate autodoc summariessphinx.ext.coverage
– Collecte les statistiques de couverture de docsphinx.ext.doctest
– Test snippets in the documentationsphinx.ext.duration
– Mesurer les durées de traitement du Sphinx- mod:`sphinx.ext.ext.extlinks” – Balisage pour raccourcir les liens externes
sphinx.ext.githubpages
– Publie les documents HTML sur GitHub Pagessphinx.ext.graphviz
– Ajouter des graphiques Graphvizsphinx.ext.ifconfig
– Inclure du contenu basé sur la configurationsphinx.ext.ext.imgconverter
– Un convertisseur d’image de référence utilisant Imagemagicksphinx.ext.inheritance_diagram
– Inclure les diagrammes d’héritage- mod:sphinx.ext.ext.intersphinx – Lien vers la documentation d’autres projets
sphinx.ext.linkcode
– Ajouter des liens externes au code source- Math support for HTML outputs in Sphinx
sphinx.ext.napoleon
– Support for NumPy and Google style docstringssphinx.ext.ext.todo
– Prise en charge des éléments todosphinx.ext.viewcode
– Add links to highlighted source code
Extensions tierces¶
You can find several extensions contributed by users in the sphinx-contrib organization. If you wish to include your extension in this organization, simply follow the instructions provided in the github-administration project. This is optional and there are several extensions hosted elsewhere. The awesome-sphinxdoc and sphinx-extensions projects are both curated lists of Sphinx packages, and many packages use the Framework :: Sphinx :: Extension and Framework :: Sphinx :: Theme trove classifiers for Sphinx extensions and themes, respectively.
Où mettre vos propres extensions ?¶
Extensions local to a project should be put within the project’s directory
structure. Set Python’s module search path, sys.path
, accordingly so that
Sphinx can find them. For example, if your extension foo.py
lies in the
exts
subdirectory of the project root, put into conf.py
:
import sys, os
sys.path.append(os.path.abspath('exts'))
extensions = ['foo']
Vous pouvez également installer des extensions n’importe où ailleurs sur sys.path
, par exemple dans le répertoire site-packages
.