Sphinx Extensions¶
Since many projects will need special features in their documentation, Sphinx allows to add “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, see Developing extensions for Sphinx.
Builtin Sphinx extensions¶
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.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.inheritance_diagram– Include inheritance diagrams
- sphinx.ext.intersphinx– Link to other projects’ documentation
- sphinx.ext.linkcode– Add external links to source code
- Math support 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
Third-party extensions¶
You can find several extensions contributed by users in the Sphinx Contrib repository. It is open for anyone who wants to maintain an extension publicly; just send a short message asking for write permissions.
There are also several extensions hosted elsewhere. The Sphinx extension survey contains a comprehensive list.
If you write an extension that you think others will find useful or you think should be included as a part of Sphinx, please write to the project mailing list (join here).
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.
E.g., 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']
You can also install extensions anywhere else on sys.path, e.g. in the
site-packages directory.
