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 Developing
extensions for Sphinx.


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

  * Directives

  * Configuration

  * Docstring preprocessing

  * Skipping members

* "sphinx.ext.autosectionlabel" -- Allow reference sections using its
  title

  * Configuration

* "sphinx.ext.autosummary" -- Generate autodoc summaries

  * **sphinx-autogen** -- generate autodoc stub pages

  * Generating stub pages automatically

  * Customizing templates

* "sphinx.ext.coverage" -- Collect doc coverage stats

* "sphinx.ext.doctest" -- Test snippets in the documentation

  * Directives

  * Skipping tests conditionally

  * Configuration

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

  * Configuration

* "sphinx.ext.inheritance_diagram" -- Include inheritance diagrams

  * Examples

  * Configuration

* "sphinx.ext.intersphinx" -- Link to other projects' documentation

  * Configuration

  * Showing all links of an Intersphinx mapping file

* "sphinx.ext.linkcode" -- Add external links to source code

  * Configuration

* Math support for HTML outputs in Sphinx

  * "sphinx.ext.imgmath" -- Render math as images

  * "sphinx.ext.mathjax" -- Render math via JavaScript

  * "sphinx.ext.jsmath" -- Render math via JavaScript

* "sphinx.ext.napoleon" -- Support for NumPy and Google style
  docstrings

  * Overview

    * Getting Started

    * Docstrings

    * Docstring Sections

    * Google vs NumPy

    * Type Annotations

  * Configuration

* "sphinx.ext.todo" -- Support for todo items

  * Configuration

* "sphinx.ext.viewcode" -- Add links to highlighted source code

  * Configuration


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

Todo: This should reference the GitHub organization now

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 and awesome-sphinxdoc 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.  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.
