Extensions
**********

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 Sphinx
Extensions API.


Built-in 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.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


Third-party extensions
======================

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.


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 "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.
