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[fuente]

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. No-op if called twice.

Sphinx.connect(event, callback)[fuente]
Sphinx.add_config_value(name, default, rebuild)[fuente]
Sphinx.set_translator(name, translator_class)[fuente]
Sphinx.add_node(node, **kwds)[fuente]
Sphinx.add_enumerable_node(node, figtype, title_getter=None, **kwds)[fuente]
Sphinx.add_directive(name, func, content, arguments, **options)[fuente]
Sphinx.add_directive(name, directiveclass)[fuente]
Sphinx.add_role(name, role)[fuente]
Sphinx.add_generic_role(name, nodeclass)[fuente]
Sphinx.add_directive_to_domain(domain, name, func, content, arguments, **options)[fuente]
Sphinx.add_directive_to_domain(domain, name, directiveclass)[fuente]
Sphinx.add_role_to_domain(domain, name, role)[fuente]
Sphinx.add_index_to_domain(domain, index)[fuente]
Sphinx.add_object_type(directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None, objname='', doc_field_types=[])[fuente]
Sphinx.add_crossref_type(directivename, rolename, indextemplate='', ref_nodeclass=None, objname='')[fuente]
Sphinx.add_latex_package(packagename, options=None)[fuente]
Sphinx.add_lexer(alias, lexer)[fuente]
Sphinx.add_autodoc_attrgetter(type, getter)[fuente]
Sphinx.add_html_theme(name, theme_path)[fuente]

Check parallel processing is allowed or not.

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

exception sphinx.application.ExtensionError[fuente]

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

Emitting events

class sphinx.application.Sphinx[fuente]
emit(event, *arguments)[fuente]
emit_firstresult(event, *arguments)[fuente]

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

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.

Nuevo en la versión 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.

Nuevo en la versión 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.

Nuevo en la versión 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.

Nuevo en la versión 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:`...`.

Nuevo en la versión 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.

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

Nuevo en la versión 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.

For a sample of how to deal with this event, look at the standard sphinx.ext.todo extension. The implementation is often similar to that of env-purge-doc, only that information is not removed, but added to the main environment from the other environment.

Nuevo en la versión 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.

Nuevo en la versión 0.5.

Distinto en la versión 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.

Nuevo en la versión 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).

Nuevo en la versión 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.

Nuevo en la versión 0.4.

Distinto en la versión 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.

Nuevo en la versión 0.5.

Checking the Sphinx version

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

sphinx.version_info = (1, 7, 9, 'final', 0)

tuple() -> empty tuple tuple(iterable) -> tuple initialized from iterable’s items

If the argument is a tuple, the return value is the same object.

The Config object

class sphinx.config.Config(dirname, filename, overrides, tags)[fuente]

Configuration file abstraction.

The template bridge

class sphinx.application.TemplateBridge[fuente]

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)[fuente]

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, context)[fuente]

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

render_string(template, context)[fuente]

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


exception sphinx.errors.SphinxError[fuente]

Base class for Sphinx errors that are shown to the user in a nicer way than normal exceptions.

exception sphinx.errors.ConfigError[fuente]
exception sphinx.errors.ExtensionError(message, orig_exc=None)[fuente]

Raised if something’s wrong with the configuration.

exception sphinx.errors.ThemeError[fuente]
exception sphinx.errors.VersionRequirementError[fuente]