Since many projects will need special features in their documentation, Sphinx allows adding “extensions” to the build process, each of which can modify almost any aspect of document processing.
This chapter describes the extensions bundled with Sphinx. For the API documentation on writing your own extension, refer to Developing extensions for Sphinx.
These extensions are built in and can be activated by respective entries in the extensions configuration value:
sphinx.ext.autodoc– Include documentation from docstrings
sphinx.ext.autosectionlabel– Allow reference sections using its title
sphinx.ext.autosummary– Generate autodoc summaries
sphinx.ext.coverage– Collect doc coverage stats
sphinx.ext.doctest– Test snippets in the documentation
sphinx.ext.duration– Measure durations of Sphinx processing
sphinx.ext.extlinks– Markup to shorten external links
sphinx.ext.githubpages– Publish HTML docs in GitHub Pages
sphinx.ext.graphviz– Add Graphviz graphs
sphinx.ext.ifconfig– Include content based on configuration
sphinx.ext.imgconverter– A reference image converter using Imagemagick
sphinx.ext.inheritance_diagram– Include inheritance diagrams
sphinx.ext.intersphinx– Link to other projects’ documentation
sphinx.ext.linkcode– Add external links to source code
- Math support for HTML outputs in Sphinx
sphinx.ext.napoleon– Support for NumPy and Google style docstrings
sphinx.ext.todo– Support for todo items
sphinx.ext.viewcode– Add links to highlighted source code
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 project contains a curated list of Sphinx packages, and many packages use the Framework :: Sphinx :: Extension and Framework :: Sphinx :: Theme trove classifiers for Sphinx extensions and themes, respectively.
Where to put your own 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
import sys, os sys.path.append(os.path.abspath('exts')) extensions = ['foo']
You can also install extensions anywhere else on
sys.path, e.g. in the