sphinx / doc / extensions.rst

Full commit
georg.brandl 186cf92 

Georg Brandl 1cdeb5e 

georg.brandl 186cf92 
Georg Brandl 1cdeb5e 

georg.brandl a2afdae 
georg.brandl b3fff67 
georg.brandl 186cf92 
Georg Brandl 1cdeb5e 
georg.brandl 4ca916f 

georg.brandl 186cf92 

georg.brandl b3fff67 

georg.brandl 186cf92 
georg.brandl b3fff67 

georg.brandl 186cf92 
georg.brandl b3fff67 
georg.brandl 186cf92 
georg.brandl 4ca916f 
Georg Brandl 2b5c644 
georg.brandl 4ca916f 
georg.brandl db6c2af 
georg.brandl be09cf0 
Georg Brandl 8d0ee9b 

georg.brandl 4ca916f 

Georg Brandl 99e97f4 
Georg Brandl 9ada6a5 

Georg Brandl 1cdeb5e 

Georg Brandl 9ada6a5 
Georg Brandl 1cdeb5e 

.. _extensions:

Sphinx Extensions

.. module:: sphinx.application
   :synopsis: Application class and extensibility interface.

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
:term:`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
:confval:`extensions` configuration value.

.. toctree::


Builtin Sphinx extensions

These extensions are built in and can be activated by respective entries in the
:confval:`extensions` configuration value:

.. toctree::


Third-party extensions

There are several extensions that are not (yet) maintained in the Sphinx
distribution.  The `Wiki at BitBucket`_ maintains a list of those.

If you write an extension that you think others will find useful, please write
to the project mailing list ( and we'll find the
proper way of including or hosting it for the public.

.. _Wiki at BitBucket:

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 ```` lies in the ``exts`` subdirectory of the
project root, put into :file:``::

   import sys, os


   extensions = ['foo']

You can also install extensions anywhere else on ``sys.path``, e.g. in the
``site-packages`` directory.