API documentation#

API Documentation can be generated with sphinx.ext.autodoc.

For example, the following directive:

Sphinx
------

.. autoclass:: sphinx.application.Sphinx
    :members:

produces the following output:

Sphinx#

class sphinx.application.Sphinx(srcdir: str, confdir: ~typing.Optional[str], outdir: str, doctreedir: str, buildername: str, confoverrides: ~typing.Dict = None, status: ~typing.IO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, warning: ~typing.IO = <_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>, freshenv: bool = False, warningiserror: bool = False, tags: ~typing.List[str] = None, verbosity: int = 0, parallel: int = 0, keep_going: bool = False)#

The main application class and extensibility interface.

Variables:

srcdir – Directory containing source.
confdir – Directory containing conf.py.
doctreedir – Directory for storing pickled doctrees.
outdir – Directory for storing build documents.

add_autodoc_attrgetter(typ: Type, getter: Callable[[Any, str, Any], Any]) → None#

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.

add_autodocumenter(cls: Any, override: bool = False) → None#

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 auto-documenting new types of objects. See the source of the autodoc module for examples on how to subclass Documenter.

If override is True, the given cls is forcedly installed even if a documenter having the same name is already installed.

See autodoc_ext_tutorial.

New in version 0.6.

Changed in version 2.2: Add override keyword.

add_builder(builder: Type[Builder], override: bool = False) → None#

Parameters:

builder – A builder class
override – If true, install the builder forcedly even if another builder is already installed as the same name

Changed in version 1.8: Add override keyword.

add_config_value(name: str, default: Any, rebuild: Union[bool, str], types: Any = ()) → None#

This is necessary for Sphinx to recognize new values and set default values accordingly.

Parameters:

name – The name of the configuration value. It is recommended to be prefixed with the extension name (ex. html_logo, epub_title)
default – The default value of the configuration.
rebuild –
The condition of rebuild. It 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.
types – The type of configuration value. A list of types can be specified. For example, [str] is used to describe a configuration that takes string value.

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.

add_crossref_type(directivename: str, rolename: str, indextemplate: str = '', ref_nodeclass: Type[TextElement] = None, objname: str = '', override: bool = False) → None#

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

Some random text here.

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

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

If override is True, the given crossref_type is forcedly installed even if a crossref_type having the same name is already installed.

Changed in version 1.8: Add override keyword.

add_css_file(filename: str, priority: int = 500, **kwargs: Any) → None#

Parameters:

filename – The filename of the CSS file. It must be relative to the HTML static path, or a full URI with scheme.
priority – The priority to determine the order of <link> tag for the CSS files. See list of “prority range for CSS files” below. If the priority of the CSS files it the same as others, the CSS files will be loaded in order of registration.
kwargs – Extra keyword arguments are included as attributes of the <link> tag.

Example:

app.add_css_file('custom.css')
# => <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" />

priority range for CSS files#
Priority	Main purpose in Sphinx
200	default priority for built-in CSS files
500	default priority for extensions
800	default priority for :confval:`html_css_files`

A CSS file can be added to the specific HTML page when an extension calls this method on :event:`html-page-context` event.

New in version 1.0.

Changed in version 1.6: Optional alternate and/or title attributes can be supplied with the arguments alternate (a Boolean) and title (a string). 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.

Changed in version 3.5: Take priority argument. Allow to add a CSS file to the specific page.

add_directive(name: str, cls: Type[Directive], override: bool = False) → None#

Parameters:

name – The name of the directive
cls – A directive class
override – If true, install the directive forcedly even if another directive is already installed as the same name

For example, a custom directive named my-directive would be added like this:

from docutils.parsers.rst import Directive, directives

class MyDirective(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):
        ...

def setup(app):
    app.add_directive('my-directive', MyDirective)

For more details, see the Docutils docs .

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.

add_directive_to_domain(domain: str, name: str, cls: Type[Directive], override: bool = False) → None#

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

Parameters:

domain – The name of target domain
name – A name of directive
cls – A directive class
override – If true, install the directive forcedly even if another directive is already installed as the same name

New in version 1.0.

Changed in version 1.8: Add override keyword.

add_domain(domain: Type[Domain], override: bool = False) → None#

Parameters:

domain – A domain class
override – If true, install the domain forcedly even if another domain is already installed as the same name

New in version 1.0.

Changed in version 1.8: Add override keyword.

add_enumerable_node(node: Type[Element], figtype: str, title_getter: Callable[[Node], str] = None, override: bool = False, **kwargs: Tuple[Callable, Callable]) → None#

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

Parameters:

node – A node class
figtype – The type of enumerable nodes. Each figtype has individual numbering sequences. As system figtypes, figure, table and code-block are defined. It is possible to add custom nodes to these default figtypes. It is also possible to define new custom figtype if a new figtype is given.
title_getter – 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.
kwargs – Visitor functions for each builder (same as add_node())
override – If true, install the node forcedly even if another node is already installed as the same name

New in version 1.4.

add_env_collector(collector: Type[EnvironmentCollector]) → None#

Refer to collector-api.

New in version 1.6.

add_event(name: str) → None#

This is needed to be able to emit it.

Parameters:: name – The name of the event

add_generic_role(name: str, nodeclass: Any, override: bool = False) → None#

If override is True, the given nodeclass is forcedly installed even if a role named as name is already installed.

New in version 0.6.

Changed in version 1.8: Add override keyword.

add_html_math_renderer(name: str, inline_renderers: Tuple[Callable, Callable] = None, block_renderers: Tuple[Callable, Callable] = None) → None#

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.

add_html_theme(name: str, theme_path: str) → None#

The name is a name of theme, and theme_path is a full path to the theme (refs: distribute-your-theme).

New in version 1.6.

add_index_to_domain(domain: str, index: Type[Index], override: bool = False) → None#

Add a custom index class to the domain named domain.

Parameters:

domain – The name of the target domain
index – The index class
override – If true, install the index forcedly even if another index is already installed as the same name

New in version 1.0.

Changed in version 1.8: Add override keyword.

add_js_file(filename: str, priority: int = 500, loading_method: Optional[str] = None, **kwargs: Any) → None#

Parameters:

filename – The filename of the JavaScript file. It must be relative to the HTML static path, a full URI with scheme, or None value. The None value is used to create inline <script> tag. See the description of kwargs below.
priority – The priority to determine the order of <script> tag for JavaScript files. See list of “prority range for JavaScript files” below. If the priority of the JavaScript files it the same as others, the JavaScript files will be loaded in order of registration.
loading_method – The loading method of the JavaScript file. 'async' or 'defer' is allowed.
kwargs – Extra keyword arguments are included as attributes of the <script> tag. A special keyword argument body is given, its value will be added between the <script> tag.

Example:

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

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

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

priority range for JavaScript files#
Priority	Main purpose in Sphinx
200	default priority for built-in JavaScript files
500	default priority for extensions
800	default priority for :confval:`html_js_files`

A JavaScript file can be added to the specific HTML page when an extension calls this method on :event:`html-page-context` event.

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.

Changed in version 3.5: Take priority argument. Allow to add a JavaScript file to the specific page.

Changed in version 4.4: Take loading_method argument. Allow to change the loading method of the JavaScript file.

add_latex_package(packagename: str, options: str = None, after_hyperref: bool = False) → None#

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

app.add_latex_package('mypackage')
# => \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.

add_lexer(alias: str, lexer: Type[Lexer]) → None#

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.

add_message_catalog(catalog: str, locale_dir: str) → None#

Parameters:

catalog – The name of the catalog
locale_dir – The base path of the message catalog

For more details, see sphinx.locale.get_translation().

New in version 1.8.

add_node(node: Type[Element], override: bool = False, **kwargs: Tuple[Callable, Optional[Callable]]) → None#

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

Parameters:

node – A node class
kwargs – Visitor functions for each builder (see below)
override – If true, install the node forcedly even if another node is already installed as the same name

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

add_object_type(directivename: str, rolename: str, indextemplate: str = '', parse_node: Callable = None, ref_nodeclass: Type[TextElement] = None, objname: str = '', doc_field_types: List = [], override: bool = False) → None#

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. 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 xref-syntax).

If override is True, the given object_type is forcedly installed even if an object_type having the same name is already installed.

Changed in version 1.8: Add override keyword.

add_post_transform(transform: Type[Transform]) → None#

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

Parameters:: transform – A transform class

add_role(name: str, role: Any, override: bool = False) → None#

Parameters:

name – The name of role
role – A role function
override – If true, install the role forcedly even if another role is already installed as the same name

For more details about role functions, see the Docutils docs .

Changed in version 1.8: Add override keyword.

add_role_to_domain(domain: str, name: str, role: Union[Callable[[str, str, str, int, Inliner, Dict[str, Any], List[str]], Tuple[List[Node], List[system_message]]], XRefRole], override: bool = False) → None#

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

Parameters:

domain – The name of the target domain
name – The name of the role
role – The role function
override – If true, install the role forcedly even if another role is already installed as the same name

New in version 1.0.

Changed in version 1.8: Add override keyword.

add_search_language(cls: Any) → None#

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.

add_source_parser(parser: Type[Parser], override: bool = False) → None#

If override is True, the given parser is forcedly installed even if a parser for the same suffix is already installed.

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.

add_source_suffix(suffix: str, filetype: str, override: bool = False) → None#

Same as :confval:`source_suffix`. The users can override this using the config setting.

If override is True, the given suffix is forcedly installed even if the same suffix is already installed.

New in version 1.8.

add_stylesheet(filename: str, alternate: bool = False, title: str = None) → None#: An alias of add_css_file().

Deprecated since version 1.8.

add_transform(transform: Type[Transform]) → None#

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

Parameters:: transform – A transform class

priority range categories for Sphinx transforms#
Priority	Main purpose in Sphinx
0-99	Fix invalid nodes by docutils. Translate a doctree.
100-299	Preparation
300-399	early
400-699	main
700-799	Post processing. Deadline to modify text and referencing.
800-899	Collect referencing and referenced nodes. Domain processing.
900-999	Finalize and clean up.

refs: Transform Priority Range Categories

connect(event: str, callback: Callable, priority: int = 500) → int#

For details on available core events and the arguments of callback functions, please see events.

Parameters:

event – The name of target event
callback – Callback function for the event
priority – The priority of the callback. The callbacks will be invoked in order of priority (ascending).

Returns:

A listener ID. It can be used for disconnect().

Changed in version 3.0: Support priority

disconnect(listener_id: int) → None#

Unregister callback by listener_id.

Parameters:: listener_id – A listener_id that connect() returns

emit(event: str, *args: Any, allowed_exceptions: Tuple[Type[Exception], ...] = ()) → List#

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!

Parameters:

event – The name of event that will be emitted
args – The arguments for the event
allowed_exceptions – The list of exceptions that are allowed in the callbacks

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

emit_firstresult(event: str, *args: Any, allowed_exceptions: Tuple[Type[Exception], ...] = ()) → Any#

Emit event and pass arguments to the callback functions.

Return the result of the first callback that doesn’t return None.

Parameters:

event – The name of event that will be emitted
args – The arguments for the event
allowed_exceptions – The list of exceptions that are allowed in the callbacks

New in version 0.5.

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

is_parallel_allowed(typ: str) → bool#

Check whether parallel processing is allowed or not.

Parameters:: typ – A type of processing; 'read' or 'write'.

require_sphinx(version: str) → None#

Check the Sphinx version if requested.

Compare version with the version of the running Sphinx, and abort the build when it is too old.

Parameters:: version – The required version in the form of major.minor.

New in version 1.0.

set_html_assets_policy(policy)#

Set the policy to include assets in HTML pages.

always: include the assets in all the pages
per_page: include the assets only in pages where they are used

set_translator(name: str, translator_class: Type[NodeVisitor], override: bool = False) → None#

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

Parameters:

name – The name of the builder for the translator
translator_class – A translator class
override – If true, install the translator forcedly even if another translator is already installed as the same name

New in version 1.3.

Changed in version 1.8: Add override keyword.

setup_extension(extname: str) → None#

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.

On this page