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 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 extensions :

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
from pathlib import Path

sys.path.append(str(Path('exts').resolve()))

extensions = ['foo']

Vous pouvez également installer des extensions n’importe où ailleurs sur sys.path, par exemple dans le répertoire site-packages.