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

class sphinx.application.Sphinx[source]

This application object has the public API described in the following.

Extension setup

These methods are usually called in an extension’s setup() function.

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


Import and setup a Sphinx extension module.

Load the extension given by the module name. Use this if your extension needs the features provided by another extension. No-op if called twice.


Check the Sphinx version if requested.

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.

Sphinx.connect(event, callback)[source]

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.

Registered callbacks will be invoked on event in the order of priority and registration. The priority is ascending order.

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

Changed in version 3.0: Support priority


Unregister callback by listener_id.


Register a new builder.

builder must be a class that inherits from Builder.

Changed in version 1.8: Add override keyword.

Sphinx.add_config_value(name, default, rebuild)[source]

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.6: Changed rebuild from a simple boolean (equivalent to '' or 'env') to a string. However, booleans are still accepted and converted internally.

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.


Register an event called name.

This is needed to be able to emit it.

Sphinx.set_translator(name, translator_class)[source]

Register or override a Docutils translator class.

This is used to register a custom output translator or to replace a builtin translator. This allows extensions to use custom translator and define custom nodes for the translator (see add_node()).

New in version 1.3.

Changed in version 1.8: Add override keyword.

Sphinx.add_node(node, \*\*kwds)[source]

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 should be one or more of 'html', 'latex', 'text', 'man', 'texinfo' or any other supported translators, 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):

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_enumerable_node(node, figtype, title_getter=None, \*\*kwds)[source]

Register a Docutils node class as a numfig target.

Sphinx numbers the node automatically. And then the users can refer it using numref.

figtype is a type of enumerable nodes. Each figtypes have individual numbering sequences. As a system figtypes, figure, table and code-block are defined. It is able to add custom nodes to these default figtypes. It is also able to define new custom figtype if new figtype is given.

title_getter is a getter function to obtain the title of node. It takes an instance of the enumerable node, and it must return its title as string. The title is used to the default title of references for ref. By default, Sphinx searches docutils.nodes.caption or docutils.nodes.title from the node as a title.

Other keyword arguments are used for node visitor functions. See the Sphinx.add_node() for details.

New in version 1.4.

Sphinx.add_directive(name, directiveclass)[source]

Register a Docutils directive.

name must be the prospective directive name. cls is a directive class which inherits docutils.parsers.rst.Directive. For more details, see the Docutils docs .

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

from docutils.parsers.rst import Directive, directives

class LiteralIncludeDirective(Directive):
    has_content = True
    required_arguments = 1
    optional_arguments = 0
    final_argument_whitespace = True
    option_spec = {
        'class': directives.class_option,
        'name': directives.unchanged,

    def run(self):

add_directive('literalinclude', LiteralIncludeDirective)

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

Deprecated since version 1.8: Docutils 0.4-style (function based) directives support is deprecated.

Changed in version 1.8: Add override keyword.

Sphinx.add_role(name, role)[source]

Register a Docutils role.

name must be the role name that occurs in the source, role the role function. Refer to the Docutils documentation for more information.

Changed in version 1.8: Add override keyword.

Sphinx.add_generic_role(name, nodeclass)[source]

Register a generic Docutils role.

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

New in version 0.6.

Changed in version 1.8: Add override keyword.


Register a domain.

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

New in version 1.0.

Changed in version 1.8: Add override keyword.

Sphinx.add_directive_to_domain(domain, name, directiveclass)[source]

Register a Docutils directive in a domain.

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

New in version 1.0.

Changed in version 1.8: Add override keyword.

Sphinx.add_role_to_domain(domain, name, role)[source]

Register a Docutils role in a domain.

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

New in version 1.0.

Changed in version 1.8: Add override keyword.

Sphinx.add_index_to_domain(domain, index)[source]

Register a custom index for a domain.

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

New in version 1.0.

Changed in version 1.8: Add override keyword.

Sphinx.add_object_type(directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None, objname='', doc_field_types=[])[source]

Register a new object type.

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 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. If the text should be treated as literal (e.g. no smart quote replacement), but not have typewriter styling, use sphinx.addnodes.literal_emphasis or sphinx.addnodes.literal_strong.

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

Changed in version 1.8: Add override keyword.

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

Register a new crossref object type.

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',

Example usage:

.. topic:: application API

The application API

Some random text here.

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

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

Changed in version 1.8: Add override keyword.


Register a Docutils transform to be applied after parsing.

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

priority range categories for Sphinx transforms


Main purpose in Sphinx


Fix invalid nodes by docutils. Translate a doctree.








Post processing. Deadline to modify text and referencing.


Collect referencing and referenced nodes. Domain processing.


Finalize and clean up.

refs: Transform Priority Range Categories


Register a Docutils transform to be applied before writing.

Add the standard docutils Transform subclass transform to the list of transforms that are applied before Sphinx writes a document.

Sphinx.add_js_file(filename, **kwargs)[source]

Register a JavaScript file to include in the HTML output.

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 , or a full URI with scheme. If the keyword argument body is given, its value will be added between the <script> tags. Extra keyword arguments are included as attributes of the <script> tag.


# => <script src="_static/example.js"></script>

app.add_js_file('example.js', async="async")
# => <script src="_static/example.js" async="async"></script>

app.add_js_file(None, body="var myVariable = 'foo';")
# => <script>var myVariable = 'foo';</script>

New in version 0.5.

Changed in version 1.8: Renamed from app.add_javascript(). And it allows keyword arguments as attributes of script tag.

Sphinx.add_css_file(filename, **kwargs)[source]

Register a stylesheet to include in the HTML output.

Add filename to the list of CSS files that the default HTML template will include. The filename must be relative to the HTML static path, or a full URI with scheme. The keyword arguments are also accepted for attributes of <link> tag.


# => <link rel="stylesheet" href="_static/custom.css" type="text/css" />

app.add_css_file('print.css', media='print')
# => <link rel="stylesheet" href="_static/print.css"
#          type="text/css" media="print" />

app.add_css_file('fancy.css', rel='alternate stylesheet', title='fancy')
# => <link rel="alternate stylesheet" href="_static/fancy.css"
#          type="text/css" title="fancy" />

New in version 1.0.

Changed in version 1.6: Optional alternate and/or title attributes can be supplied with the alternate (of boolean type) and title (a string) arguments. The default is no title and alternate = False. For more information, refer to the documentation.

Changed in version 1.8: Renamed from app.add_stylesheet(). And it allows keyword arguments as attributes of link tag.

Sphinx.add_latex_package(packagename, options=None)[source]

Register a package to include in the LaTeX source code.

Add packagename to the list of packages that LaTeX source code will include. If you provide options, it will be taken to usepackage declaration. If you set after_hyperref truthy, the package will be loaded after hyperref package.

# => \usepackage{mypackage}
app.add_latex_package('mypackage', 'foo,bar')
# => \usepackage[foo,bar]{mypackage}

New in version 1.3.

New in version 3.1: after_hyperref option.

Sphinx.add_lexer(alias, lexer)[source]

Register a new lexer for source code.

Use lexer to highlight code blocks with the given language alias.

New in version 0.6.

Changed in version 2.1: Take a lexer class as an argument. An instance of lexers are still supported until Sphinx-3.x.


Register a new documenter class for the autodoc extension.

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.


Add real docs for Documenter and subclassing

New in version 0.6.

Changed in version 2.2: Add override keyword.

Sphinx.add_autodoc_attrgetter(type, getter)[source]

Register a new getattr-like function for the autodoc extension.

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


Register a new language for the HTML search index.

Add cls, which must be a subclass of, 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 html_search_language.

New in version 1.1.

Sphinx.add_source_suffix(suffix, filetype)[source]

Register a suffix of source files.

Same as source_suffix. The users can override this using the setting.

New in version 1.8.


Register a parser class.

New in version 1.4.

Changed in version 1.8: suffix argument is deprecated. It only accepts parser argument. Use add_source_suffix() API to register suffix instead.

Changed in version 1.8: Add override keyword.


Register an environment collector class.

Refer to Environment Collector API.

New in version 1.6.

Sphinx.add_html_theme(name, theme_path)[source]

Register a HTML Theme.

The name is a name of theme, and path is a full path to the theme (refs: Distribute your theme as a Python package).

New in version 1.6.

Sphinx.add_html_math_renderer(name, inline_renderers, block_renderers)[source]

Register a math renderer for HTML.

The name is a name of math renderer. Both inline_renderers and block_renderers are used as visitor functions for the HTML writer: the former for inline math node (nodes.math), the latter for block math node (nodes.math_block). Regarding visitor functions, see add_node() for details.

New in version 1.8.

Sphinx.add_message_catalog(catalog, locale_dir)[source]

Register a message catalog.

The catalog is a name of catalog, and locale_dir is a base path of message catalog. For more details, see sphinx.locale.get_translation().

New in version 1.8.


Check parallel processing is allowed or not.

typ is a type of processing; 'read' or 'write'.

exception sphinx.application.ExtensionError

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

Emitting events

class sphinx.application.Sphinx[source]
emit(event, \*arguments)[source]

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!

Changed in version 3.1: Added allowed_exceptions to specify path-through exceptions

emit_firstresult(event, \*arguments)[source]

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.

Changed in version 3.1: Added allowed_exceptions to specify path-through exceptions

Sphinx runtime information

The application object also provides runtime information as attributes.


Target project. See Project.


Source directory.


Directory containing


Directory for storing pickled doctrees.


Directory for storing built document.

Sphinx core events

These events are known to the core. The arguments shown are given to the registered event handlers. Use Sphinx.connect() in an extension’s setup function (note that can also have a setup function) to connect handlers to the events. Example:

def source_read_handler(app, docname, source):
    print('do something here...')

def setup(app):
    app.connect('source-read', source_read_handler)

Below is an overview of each event that happens during a build. In the list below, we include the event name, its callback parameters, and the input and output type for that event:

1. event.config-inited(app,config)
2. event.builder-inited(app)
3. event.env-get-outdated(app, env, added, changed, removed)
4. event.env-before-read-docs(app, env, docnames)

for docname in docnames:
   5.  event.env-purge-doc(app, env, docname)
   if doc changed and not removed:
      6. source-read(app, docname, source)
      7. run source parsers: text -> docutils.document (parsers can be added with the app.add_source_parser() API)
      8. apply transforms (by priority): docutils.document -> docutils.document
         - event.doctree-read(app, doctree) is called in the middly of transforms,
           transforms come before/after this event depending on their priority.
9. (if running in parallel mode, for each process) event.env-merged-info(app, env, docnames, other)
10. event.env-updated(app, env)
11. event.env-get-updated(app, env)
11. event.env-check-consistency(app, env)

# For builders that output a single page, they are first joined into a single doctree before post-transforms/doctree-resolved
for docname in docnames:
   12. apply post-transforms (by priority): docutils.document -> docutils.document
   13. event.doctree-resolved(app, doctree, docname)
       - (for any reference node that fails to resolve) event.missing-reference(env, node, contnode)

14. Generate output files

15., exception)

Here is a more detailed list of these events.


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

config-inited(app, config)

Emitted when the config object has been initialized.

New in version 1.8.

env-get-outdated(app, env, added, changed, removed)

Emitted when the environment determines which source files have changed and should be re-read. added, changed and removed are sets of docnames that the environment has determined. You can return a list of docnames to re-read in addition to these.

New in version 1.1.

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.

env-before-read-docs(app, env, docnames)

Emitted after the environment has determined the list of all added and changed files and just before it reads them. It allows extension authors to reorder the list of docnames (inplace) before processing, or add more docnames that Sphinx did not consider changed (but never add any docnames that are not in env.found_docs).

You can also remove document names; do this with caution since it will make Sphinx treat changed files as unchanged.

New in version 1.3.

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.

object-description-transform(app, domain, objtype, contentnode)

Emitted when an object description directive has run. The domain and objtype arguments are strings indicating object description of the object. And contentnode is a content for the object. It can be modified in-place.

New in version 2.4.

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 an 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. If the handler can not resolve the cross-reference, it can either return None to let other handlers try, or raise NoUri to prevent other handlers in trying and suppress a warning about this cross-reference being unresolved.

  • env – The build environment (app.builder.env).

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

  • 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-merge-info(app, env, docnames, other)

This event is only emitted when parallel reading of documents is enabled. It is emitted once for every subprocess that has read some documents.

You must handle this event in an extension that stores data in the environment in a custom location. Otherwise the environment in the main process will not be aware of the information stored in the subprocess.

other is the environment object from the subprocess, env is the environment from the main process. docnames is a set of document names that have been read in the subprocess.

New in version 1.3.

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.

You can return an iterable of docnames from the handler. These documents will then be considered updated, and will be (re-)written during the writing phase.

New in version 0.5.

Changed in version 1.3: The handlers’ return value is now used.

env-check-consistency(app, env)

Emitted when Consistency checks phase. You can check consistency of metadata for whole of documents.

New in version 1.6: As a experimental event


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.

You can return a string from the handler, it will then replace 'page.html' as the HTML template for this page.

New in version 0.4.

Changed in version 1.3: The return value can now specify a template name.

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.

Checking the Sphinx version

Use this to adapt your extension to API changes in Sphinx.

sphinx.version_info = (4, 0, 0, 'beta', 0)

Version info for better programmatic use.

A tuple of five elements; for Sphinx version 1.2.1 beta 3 this would be (1, 2, 1, 'beta', 3). The fourth element can be one of: alpha, beta, rc, final. final always has 0 as the last element.

New in version 1.2: Before version 1.2, check the string sphinx.__version__.

The Config object

class sphinx.config.Config(config: Dict[str, Any] = {}, overrides: Dict[str, Any] = {})[source]

Configuration file abstraction.

The config object makes the values of all config values available as attributes.

It is exposed via the sphinx.application.Application.config and sphinx.environment.Environment.config attributes. For example, to get the value of language, use either app.config.language or env.config.language.

The template bridge

class sphinx.application.TemplateBridge[source]

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: Builder, theme: sphinx.theming.Theme = None, dirs: List[str] = None)None[source]

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.


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: str, context: Dict)None[source]

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

render_string(template: str, context: Dict)str[source]

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


exception sphinx.errors.SphinxError[source]

Base class for Sphinx errors.

This is the base class for “nice” exceptions. When such an exception is raised, Sphinx will abort the build and present the exception category and message to the user.

Extensions are encouraged to derive from this exception for their custom errors.

Exceptions not derived from SphinxError are treated as unexpected and shown to the user with a part of the traceback (and the full traceback saved in a temporary file).


Description of the exception “category”, used in converting the exception to a string (“category: message”). Should be set accordingly in subclasses.

exception sphinx.errors.ConfigError[source]

Configuration error.

exception sphinx.errors.ExtensionError(message: str, orig_exc: Exception = None)[source]

Extension error.

exception sphinx.errors.ThemeError[source]

Theme error.

exception sphinx.errors.VersionRequirementError[source]

Incompatible Sphinx version error.