
Extension API
*************

Each Sphinx extension is a Python module with at least a ``setup()``
function. This function is called at initialization time with one
argument, the application object representing the Sphinx process.
This application object has the following public API:

Sphinx.setup_extension(name)

   Load the extension given by the module *name*.  Use this if your
   extension needs the features provided by another extension.

Sphinx.add_builder(builder)

   Register a new builder.  *builder* must be a class that inherits
   from ``Builder``.

Sphinx.add_config_value(name, default, rebuild)

   Register a configuration value.  This is necessary for Sphinx to
   recognize new values and set default values accordingly.  The
   *name* should be prefixed with the extension name, to avoid
   clashes.  The *default* value can be any Python object.  The string
   value *rebuild* must be one of those values:

   * ``'env'`` if a change in the setting only takes effect when a
     document is parsed -- this means that the whole environment must
     be rebuilt.

   * ``'html'`` if a change in the setting needs a full rebuild of
     HTML documents.

   * ``''`` if a change in the setting will not need any special
     rebuild.

   Changed in version 0.4: If the *default* value is a callable, it
   will be called with the config object as its argument in order to
   get the default value.  This can be used to implement config values
   whose default depends on other values.

   Changed in version 0.6: Changed *rebuild* from a simple boolean
   (equivalent to ``''`` or ``'env'``) to a string.  However, booleans
   are still accepted and converted internally.

Sphinx.add_domain(domain)

   Make the given *domain* (which must be a class; more precisely, a
   subclass of ``Domain``) known to Sphinx.

   New in version 1.0.

Sphinx.override_domain(domain)

   Make the given *domain* class known to Sphinx, assuming that there
   is already a domain with its ``.name``.  The new domain must be a
   subclass of the existing one.

   New in version 1.0.

Sphinx.add_index_to_domain(domain, index)

   Add a custom *index* class to the domain named *domain*.  *index*
   must be a subclass of ``Index``.

   New in version 1.0.

Sphinx.add_event(name)

   Register an event called *name*.  This is needed to be able to emit
   it.

Sphinx.add_node(node, **kwds)

   Register a Docutils node class.  This is necessary for Docutils
   internals. It may also be used in the future to validate nodes in
   the parsed documents.

   Node visitor functions for the Sphinx HTML, LaTeX, text and manpage
   writers can be given as keyword arguments: the keyword must be one
   or more of ``'html'``, ``'latex'``, ``'text'``, ``'man'``, the
   value a 2-tuple of ``(visit, depart)`` methods.  ``depart`` can be
   ``None`` if the ``visit`` function raises
   ``docutils.nodes.SkipNode``.  Example:

      class math(docutils.nodes.Element): pass

      def visit_math_html(self, node):
          self.body.append(self.starttag(node, 'math'))
      def depart_math_html(self, node):
          self.body.append('</math>')

      app.add_node(math, html=(visit_math_html, depart_math_html))

   Obviously, translators for which you don't specify visitor methods
   will choke on the node when encountered in a document to translate.

   Changed in version 0.5: Added the support for keyword arguments
   giving visit functions.

Sphinx.add_directive(name, func, content, arguments, **options)
Sphinx.add_directive(name, directiveclass)

   Register a Docutils directive.  *name* must be the prospective
   directive name.  There are two possible ways to write a directive:

   * In the docutils 0.4 style, *obj* is the directive function.
     *content*, *arguments* and *options* are set as attributes on the
     function and determine whether the directive has content,
     arguments and options, respectively.  **This style is
     deprecated.**

   * In the docutils 0.5 style, *directiveclass* is the directive
     class.  It must already have attributes named *has_content*,
     *required_arguments*, *optional_arguments*,
     *final_argument_whitespace* and *option_spec* that correspond to
     the options for the function way.  See the Docutils docs for
     details.

     The directive class normally must inherit from the class
     ``docutils.parsers.rst.Directive``.  When writing a directive for
     usage in a Sphinx extension, you inherit from
     ``sphinx.util.compat.Directive`` instead which does the right
     thing even on docutils 0.4 (which doesn't support directive
     classes otherwise).

   For example, the (already existing) ``literalinclude`` directive
   would be added like this:

      from docutils.parsers.rst import directives
      add_directive('literalinclude', literalinclude_directive,
                    content = 0, arguments = (1, 0, 0),
                    linenos = directives.flag,
                    language = direcitves.unchanged,
                    encoding = directives.encoding)

   Changed in version 0.6: Docutils 0.5-style directive classes are
   now supported.

Sphinx.add_directive_to_domain(domain, name, func, content, arguments, **options)
Sphinx.add_directive_to_domain(domain, name, directiveclass)

   Like ``add_directive()``, but the directive is added to the domain
   named *domain*.

   New in version 1.0.

Sphinx.add_role(name, role)

   Register a Docutils role.  *name* must be the role name that occurs
   in the source, *role* the role function (see the Docutils
   documentation on details).

Sphinx.add_role_to_domain(domain, name, role)

   Like ``add_role()``, but the role is added to the domain named
   *domain*.

   New in version 1.0.

Sphinx.add_generic_role(name, nodeclass)

   Register a Docutils role that does nothing but wrap its contents in
   the node given by *nodeclass*.

   New in version 0.6.

Sphinx.add_object_type(directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None, objname='')

   This method is a very convenient way to add a new *object* type
   that can be cross-referenced.  It will do this:

   * Create a new directive (called *directivename*) for documenting
     an object. It will automatically add index entries if
     *indextemplate* is nonempty; if given, it must contain exactly
     one instance of ``%s``.  See the example below for how the
     template will be interpreted.

   * Create a new role (called *rolename*) to cross-reference to these
     object descriptions.

   * If you provide *parse_node*, it must be a function that takes a
     string and a docutils node, and it must populate the node with
     children parsed from the string.  It must then return the name of
     the item to be used in cross-referencing and index entries.  See
     the ``conf.py`` file in the source for this documentation for an
     example.

   * The *objname* (if not given, will default to *directivename*)
     names the type of object.  It is used when listing objects, e.g.
     in search results.

   For example, if you have this call in a custom Sphinx extension:

      app.add_object_type('directive', 'dir', 'pair: %s; directive')

   you can use this markup in your documents:

      .. rst:directive:: function

         Document a function.

      <...>

      See also the :rst:dir:`function` directive.

   For the directive, an index entry will be generated as if you had
   prepended

      .. index:: pair: function; directive

   The reference node will be of class ``literal`` (so it will be
   rendered in a proportional font, as appropriate for code) unless
   you give the *ref_nodeclass* argument, which must be a docutils
   node class (most useful are ``docutils.nodes.emphasis`` or
   ``docutils.nodes.strong`` -- you can also use
   ``docutils.nodes.generated`` if you want no further text
   decoration).

   For the role content, you have the same syntactical possibilities
   as for standard Sphinx roles (see *Cross-referencing syntax*).

   This method is also available under the deprecated alias
   ``add_description_unit``.

Sphinx.add_crossref_type(directivename, rolename, indextemplate='', ref_nodeclass=None, objname='')

   This method is very similar to ``add_object_type()`` except that
   the directive it generates must be empty, and will produce no
   output.

   That means that you can add semantic targets to your sources, and
   refer to them using custom roles instead of generic ones (like
   ``ref``).  Example call:

      app.add_crossref_type('topic', 'topic', 'single: %s', docutils.nodes.emphasis)

   Example usage:

      .. topic:: application API

      The application API
      -------------------

      <...>

      See also :topic:`this section <application API>`.

   (Of course, the element following the ``topic`` directive needn't
   be a section.)

Sphinx.add_transform(transform)

   Add the standard docutils ``Transform`` subclass *transform* to the
   list of transforms that are applied after Sphinx parses a reST
   document.

Sphinx.add_javascript(filename)

   Add *filename* to the list of JavaScript files that the default
   HTML template will include.  The filename must be relative to the
   HTML static path, see ``the docs for the config value``.  A full
   URI with scheme, like ``http://example.org/foo.js``, is also
   supported.

   New in version 0.5.

Sphinx.add_stylesheet(filename)

   Add *filename* to the list of CSS files that the default HTML
   template will include.  Like for ``add_javascript()``, the filename
   must be relative to the HTML static path.

   New in version 1.0.

Sphinx.add_lexer(alias, lexer)

   Use *lexer*, which must be an instance of a Pygments lexer class,
   to highlight code blocks with the given language *alias*.

   New in version 0.6.

Sphinx.add_autodocumenter(cls)

   Add *cls* as a new documenter class for the ``sphinx.ext.autodoc``
   extension.  It must be a subclass of
   ``sphinx.ext.autodoc.Documenter``. This allows to auto-document new
   types of objects.  See the source of the autodoc module for
   examples on how to subclass ``Documenter``.

   New in version 0.6.

Sphinx.add_autodoc_attrgetter(type, getter)

   Add *getter*, which must be a function with an interface compatible
   to the ``getattr()`` builtin, as the autodoc attribute getter for
   objects that are instances of *type*.  All cases where autodoc
   needs to get an attribute of a type are then handled by this
   function instead of ``getattr()``.

   New in version 0.6.

Sphinx.connect(event, callback)

   Register *callback* to be called when *event* is emitted.  For
   details on available core events and the arguments of callback
   functions, please see *Sphinx core events*.

   The method returns a "listener ID" that can be used as an argument
   to ``disconnect()``.

Sphinx.disconnect(listener_id)

   Unregister callback *listener_id*.

Sphinx.emit(event, *arguments)

   Emit *event* and pass *arguments* to the callback functions.
   Return the return values of all callbacks as a list.  Do not emit
   core Sphinx events in extensions!

Sphinx.emit_firstresult(event, *arguments)

   Emit *event* and pass *arguments* to the callback functions.
   Return the result of the first callback that doesn't return
   ``None``.

   New in version 0.5.

Sphinx.require_sphinx(version)

   Compare *version* (which must be a ``major.minor`` version string,
   e.g. ``'1.1'``) with the version of the running Sphinx, and abort
   the build when it is too old.

   New in version 1.0.

exception exception sphinx.application.ExtensionError

   All these functions raise this exception if something went wrong
   with the extension API.

Examples of using the Sphinx extension API can be seen in the
``sphinx.ext`` package.


Sphinx core events
==================

These events are known to the core.  The arguments shown are given to
the registered event handlers.

builder-inited(app)

   Emitted when the builder object has been created.  It is available
   as ``app.builder``.

env-purge-doc(app, env, docname)

   Emitted when all traces of a source file should be cleaned from the
   environment, that is, if the source file is removed or before it is
   freshly read.  This is for extensions that keep their own caches in
   attributes of the environment.

   For example, there is a cache of all modules on the environment.
   When a source file has been changed, the cache's entries for the
   file are cleared, since the module declarations could have been
   removed from the file.

   New in version 0.5.

source-read(app, docname, source)

   Emitted when a source file has been read.  The *source* argument is
   a list whose single element is the contents of the source file.
   You can process the contents and replace this item to implement
   source-level transformations.

   For example, if you want to use ``$`` signs to delimit inline math,
   like in LaTeX, you can use a regular expression to replace
   ``$...$`` by ``:math:`...```.

   New in version 0.5.

doctree-read(app, doctree)

   Emitted when a doctree has been parsed and read by the environment,
   and is about to be pickled.  The *doctree* can be modified in-
   place.

missing-reference(app, env, node, contnode)

   Emitted when a cross-reference to a Python module or object cannot
   be resolved.  If the event handler can resolve the reference, it
   should return a new docutils node to be inserted in the document
   tree in place of the node *node*.  Usually this node is a
   ``reference`` node containing *contnode* as a child.

   Param env:
      The build environment (``app.builder.env``).

   Param node:
      The ``pending_xref`` node to be resolved.  Its attributes
      ``reftype``, ``reftarget``, ``modname`` and ``classname``
      attributes determine the type and target of the reference.

   Param contnode:
      The node that carries the text and formatting inside the future
      reference and should be a child of the returned reference node.

   New in version 0.5.

doctree-resolved(app, doctree, docname)

   Emitted when a doctree has been "resolved" by the environment, that
   is, all references have been resolved and TOCs have been inserted.
   The *doctree* can be modified in place.

   Here is the place to replace custom nodes that don't have visitor
   methods in the writers, so that they don't cause errors when the
   writers encounter them.

env-updated(app, env)

   Emitted when the ``update()`` method of the build environment has
   completed, that is, the environment and all doctrees are now up-to-
   date.

   New in version 0.5.

html-collect-pages(app)

   Emitted when the HTML builder is starting to write non-document
   pages.  You can add pages to write by returning an iterable from
   this event consisting of ``(pagename, context, templatename)``.

   New in version 1.0.

html-page-context(app, pagename, templatename, context, doctree)

   Emitted when the HTML builder has created a context dictionary to
   render a template with -- this can be used to add custom elements
   to the context.

   The *pagename* argument is the canonical name of the page being
   rendered, that is, without ``.html`` suffix and using slashes as
   path separators.  The *templatename* is the name of the template to
   render, this will be ``'page.html'`` for all pages from reST
   documents.

   The *context* argument is a dictionary of values that are given to
   the template engine to render the page and can be modified to
   include custom values.  Keys must be strings.

   The *doctree* argument will be a doctree when the page is created
   from a reST documents; it will be ``None`` when the page is created
   from an HTML template alone.

   New in version 0.4.

build-finished(app, exception)

   Emitted when a build has finished, before Sphinx exits, usually
   used for cleanup.  This event is emitted even when the build
   process raised an exception, given as the *exception* argument.
   The exception is reraised in the application after the event
   handlers have run.  If the build process raised no exception,
   *exception* will be ``None``.  This allows to customize cleanup
   actions depending on the exception status.

   New in version 0.5.


The template bridge
===================

class class sphinx.application.TemplateBridge

   This class defines the interface for a "template bridge", that is,
   a class that renders templates given a template name and a context.

   init(builder, theme=None, dirs=None)

      Called by the builder to initialize the template system.

      *builder* is the builder object; you'll probably want to look at
      the value of ``builder.config.templates_path``.

      *theme* is a ``sphinx.theming.Theme`` object or None; in the
      latter case, *dirs* can be list of fixed directories to look for
      templates.

   newest_template_mtime()

      Called by the builder to determine if output files are outdated
      because of template changes.  Return the mtime of the newest
      template file that was changed.  The default implementation
      returns ``0``.

   render(template, context)

      Called by the builder to render a template given as a filename
      with a specified context (a Python dictionary).

   render_string(template, context)

      Called by the builder to render a template given as a string
      with a specified context (a Python dictionary).


Domain API
==========

class class sphinx.domains.Domain(env)

   A Domain is meant to be a group of "object" description directives
   for objects of a similar nature, and corresponding roles to create
   references to them.  Examples would be Python modules, classes,
   functions etc., elements of a templating language, Sphinx roles and
   directives, etc.

   Each domain has a separate storage for information about existing
   objects and how to reference them in *self.data*, which must be a
   dictionary.  It also must implement several functions that expose
   the object information in a uniform way to parts of Sphinx that
   allow the user to reference or search for objects in a domain-
   agnostic way.

   About *self.data*: since all object and cross-referencing
   information is stored on a BuildEnvironment instance, the
   *domain.data* object is also stored in the *env.domaindata* dict
   under the key *domain.name*.  Before the build process starts,
   every active domain is instantiated and given the environment
   object; the *domaindata* dict must then either be nonexistent or a
   dictionary whose 'version' key is equal to the domain class'
   ``data_version`` attribute.  Otherwise, *IOError* is raised and the
   pickled environment is discarded.

   clear_doc(docname)

      Remove traces of a document in the domain-specific inventories.

   directive(name)

      Return a directive adapter class that always gives the
      registered directive its full name ('domain:name') as
      ``self.name``.

   get_objects()

      Return an iterable of "object descriptions", which are tuples
      with five items:

      * *name*     -- fully qualified name

      * *dispname* -- name to display when searching/linking

      * *type*     -- object type, a key in ``self.object_types``

      * *docname*  -- the document where it is to be found

      * *anchor*   -- the anchor name for the object

      * *priority* -- how "important" the object is (determines
        placement in search results)

        * 1: default priority (placed before full-text matches)

        * 0: object is important (placed before default-priority
          objects)

        * 2: object is unimportant (placed after full-text matches)

        * -1: object should not show up in search at all

   get_type_name(type, primary=False)

      Return full name for given ObjType.

   process_doc(env, docname, document)

      Process a document after it is read by the environment.

   resolve_xref(env, fromdocname, builder, typ, target, node, contnode)

      Resolve the ``pending_xref`` *node* with the given *typ* and
      *target*.

      This method should return a new node, to replace the xref node,
      containing the *contnode* which is the markup content of the
      cross-reference.

      If no resolution can be found, None can be returned; the xref
      node will then given to the 'missing-reference' event, and if
      that yields no resolution, replaced by *contnode*.

      The method can also raise ``sphinx.environment.NoUri`` to
      suppress the 'missing-reference' event being emitted.

   role(name)

      Return a role adapter function that always gives the registered
      role its full name ('domain:name') as the first argument.

   data_version

      data version, bump this when the format of *self.data* changes

   directives

      directive name -> directive class

   indices

      a list of Index subclasses

   initial_data

      data value for a fresh environment

   label

      domain label: longer, more descriptive (used in messages)

   name

      domain name: should be short, but unique

   object_types

      type (usually directive) name -> ObjType instance

   roles

      role name -> role callable

class class sphinx.domains.ObjType(lname, *roles, **attrs)

   An ObjType is the description for a type of object that a domain
   can document.  In the object_types attribute of Domain subclasses,
   object type names are mapped to instances of this class.

   Constructor arguments:

   * *lname*: localized name of the type (do not include domain name)

   * *roles*: all the roles that can refer to an object of this type

   * *attrs*: object attributes -- currently only "searchprio" is
     known, which defines the object's priority in the full-text
     search index, see ``Domain.get_objects()``.

class class sphinx.domains.Index(domain)

   An Index is the description for a domain-specific index.  To add an
   index to a domain, subclass Index, overriding the three name
   attributes:

   * *name* is an identifier used for generating file names.

   * *localname* is the section title for the index.

   * *shortname* is a short name for the index, for use in the
     relation bar in HTML output.  Can be empty to disable entries in
     the relation bar.

   and providing a ``generate()`` method.  Then, add the index class
   to your domain's *indices* list.  Extensions can add indices to
   existing domains using ``add_index_to_domain()``.

   generate(docnames=None)

      Return entries for the index given by *name*.  If *docnames* is
      given, restrict to entries referring to these docnames.

      The return value is a tuple of ``(content, collapse)``, where
      *collapse* is a boolean that determines if sub-entries should
      start collapsed (for output formats that support collapsing sub-
      entries).

      *content* is a sequence of ``(letter, entries)`` tuples, where
      *letter* is the "heading" for the given *entries*, usually the
      starting letter.

      *entries* is a sequence of single entries, where a single entry
      is a sequence ``[name, subtype, docname, anchor, extra,
      qualifier, descr]``. The items in this sequence have the
      following meaning:

      * *name* -- the name of the index entry to be displayed

      * *subtype* -- sub-entry related type: 0 -- normal entry 1 --
        entry with sub-entries 2 -- sub-entry

      * *docname* -- docname where the entry is located

      * *anchor* -- anchor for the entry within *docname*

      * *extra* -- extra info for the entry

      * *qualifier* -- qualifier for the description

      * *descr* -- description for the entry

      Qualifier and description are not rendered e.g. in LaTeX output.
