sphinx.application.Sphinx

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.

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 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 :ref:`autodoc_ext_tutorial`.

Register a new builder.

Register a configuration value.

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

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 :rst:role:`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.

Register a stylesheet to include in the HTML output.

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

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

Register a Docutils directive.

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 .

Register a Docutils directive in a domain.

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

Register a domain.

Register a Docutils node class as a numfig target.

Sphinx numbers the node automatically. And then the users can refer it using :rst:role:`numref`.

Register an environment collector class.

Refer to :ref:`collector-api`.

Register an event called name.

This is needed to be able to emit it.

Register a generic Docutils role.

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

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

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.

Register a HTML Theme.

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

Register a custom index for a domain.

Add a custom index class to the domain named domain.

Register a JavaScript file to include in the HTML output.

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>

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

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

Register a new lexer for source code.

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

Register a message catalog.

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

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

Register a new object type.

This method is a very convenient way to add a new :term:`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:`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 :ref:`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.

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.

Register a Docutils role.

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

Register a Docutils role in a domain.

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

Register a new language for the HTML search index.

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

Register a parser class.

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

Register a suffix of source files.

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.

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.

refs: Transform Priority Range Categories

Register callback to be called when event is emitted.

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

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!

Emit event and pass arguments to the callback functions.

Return the result of the first callback that doesn't return 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.

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 a custom translator and define custom nodes for the translator (see add_node).

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.