
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.mathjax" -- Render math via JavaScript
  * "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.
