
Sphinx Extensions
*****************

Since many projects will need special features in their documentation,
Sphinx is designed to be extensible on several levels.

This is what you can do in an extension: First, you can add new
*builder*s to support new output formats or actions on the parsed
documents.  Then, it is possible to register custom reStructuredText
roles and directives, extending the markup.  And finally, there are
so-called "hook points" at strategic places throughout the build
process, where an extension can register a hook and run specialized
code.

An extension is simply a Python module.  When an extension is loaded,
Sphinx imports this module and executes its ``setup()`` function,
which in turn notifies Sphinx of everything the extension offers --
see the extension tutorial for examples.

The configuration file itself can be treated as an extension if it
contains a ``setup()`` function.  All other extensions to load must be
listed in the ``extensions`` configuration value.

* Tutorial: Writing a simple extension
  * Build Phases
  * Extension Design
  * The Setup Function
  * The Node Classes
  * The Directive Classes
  * The Event Handlers
* Extension API
  * Sphinx core events
  * The template bridge
  * Domain API
* Writing new builders

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
  * Docstring preprocessing
  * Skipping members
* ``sphinx.ext.autosummary`` -- Generate autodoc summaries
  * **sphinx-autogen** -- generate autodoc stub pages
  * Generating stub pages automatically
  * Customizing templates
* ``sphinx.ext.doctest`` -- Test snippets in the documentation
* ``sphinx.ext.intersphinx`` -- Link to other projects' documentation
* Math support in Sphinx
  * ``sphinx.ext.pngmath`` -- Render math as PNG images
  * ``sphinx.ext.jsmath`` -- Render math via JavaScript
* ``sphinx.ext.graphviz`` -- Add Graphviz graphs
* ``sphinx.ext.inheritance_diagram`` -- Include inheritance diagrams
* ``sphinx.ext.refcounting`` -- Keep track of reference counting
  behavior
* ``sphinx.ext.ifconfig`` -- Include content based on configuration
* ``sphinx.ext.coverage`` -- Collect doc coverage stats
* ``sphinx.ext.todo`` -- Support for todo items
* ``sphinx.ext.extlinks`` -- Markup to shorten external links
* ``sphinx.ext.viewcode`` -- Add links to highlighted source code
* ``sphinx.ext.oldcmarkup`` -- Compatibility extension for old C
  markup

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 Wiki at
BitBucket maintains a list of those.

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.
