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', 'texinfo', 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 must inherit from the class docutils.parsers.rst.Directive.

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='', doc_field_types=[])

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 :confval:`the docs for the config value <html_static_path>`. 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, or a full URI with scheme.

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.add_search_language(cls)

Add cls, which must be a subclass of sphinx.search.SearchLanguage, as a support language for building the HTML full-text search index. The class must have a lang attribute that indicates the language it should be used for. See :confval:`html_search_language`.

New in version 1.1.

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 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.

The template bridge

Domain API