doc/extensions.rst

.. _extensions:

Sphinx Extensions
=================

Since many projects will need special features in their documentation, Sphinx
allows to add "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, see :ref:`dev-extensions`.

Builtin Sphinx extensions
-------------------------

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

.. toctree::

   ext/autodoc
   ext/autosummary
   ext/doctest
   ext/intersphinx
   ext/math
   ext/graphviz
   ext/inheritance
   ext/ifconfig
   ext/coverage
   ext/todo
   ext/extlinks
   ext/viewcode
   ext/linkcode
   ext/oldcmarkup


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 <https://groups.google.com/group/sphinx-dev>`_).

.. _Wiki at BitBucket: https://bitbucket.org/birkenfeld/sphinx/wiki/Home
.. _Sphinx Contrib: https://bitbucket.org/birkenfeld/sphinx-contrib


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 :file:`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.