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 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, 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 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.
- builder-inited(app)
Emitted when the builder object has been created. It is available as app.builder.
- 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.
- 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.
Parameters: - 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-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.
Checking the Sphinx version
Use this to adapt your extension to API changes in Sphinx.
- sphinx.version_info
A tuple of five elements; for Sphinx version 1.2.1 beta 3 this would be (1, 2, 1, 'beta', 3).
New in version 1.2: Before version 1.2, check the string sphinx.__version__.
The template bridge
- 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 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.
- dangling_warnings = {}
role name -> a warning message if reference is missing
- data_version = 0
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 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 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.