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

   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.

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

static Sphinx.require_sphinx(version: tuple[int, int] | 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"
      or "(major, minor)".

   New in version 1.0.

   Changed in version 7.1: Type of *version* now allows "(major,
   minor)" form.

Sphinx.connect(event: str, callback: Callable, priority: int = 500) -> int

   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.

   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*

Sphinx.disconnect(listener_id: int) -> None

   Unregister callback by *listener_id*.

   Parameters:
      **listener_id** -- A listener_id that "connect()" returns

Sphinx.add_builder(builder: type[Builder], override: bool = False) -> None

   Register a new builder.

   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.

Sphinx.add_config_value(name: str, default: Any, rebuild: bool | str, types: Any = ()) -> None

   Register a configuration value.

   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.

Sphinx.add_event(name: str) -> None

   Register an event called *name*.

   This is needed to be able to emit it.

   Parameters:
      **name** -- The name of the event

Sphinx.set_translator(name: str, translator_class: type[docutils.nodes.NodeVisitor], override: bool = False) -> None

   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()").

   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.

Sphinx.add_node(node: type[Element], override: bool = False, **kwargs: tuple[Callable, Callable | None]) -> None

   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.

   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.

Sphinx.add_enumerable_node(node: type[Element], figtype: str, title_getter: TitleGetter | None = None, override: bool = False, **kwargs: tuple[Callable, Callable]) -> None

   Register a Docutils node class as a numfig target.

   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.

Sphinx.add_directive(name: str, cls: type[docutils.parsers.rst.Directive], override: bool = False) -> None

   Register a Docutils directive.

   Parameters:
      * **name** -- The name of the directive

      * **cls** -- A directive class

      * **override** -- If false, do not install it if another
        directive is already installed as the same name If true,
        unconditionally install the 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 .

   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: str, role: Any, override: bool = False) -> None

   Register a Docutils role.

   Parameters:
      * **name** -- The name of role

      * **role** -- A role function

      * **override** -- If false, do not install it if another role is
        already installed as the same name If true, unconditionally
        install the role.

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

   Changed in version 1.8: Add *override* keyword.

Sphinx.add_generic_role(name: str, nodeclass: Any, override: bool = False) -> None

   Register a generic Docutils role.

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

   Parameters:
      **override** -- If false, do not install it if another role is
      already installed as the same name If true, unconditionally
      install the role.

   New in version 0.6.

   Changed in version 1.8: Add *override* keyword.

Sphinx.add_domain(domain: type[sphinx.domains.Domain], override: bool = False) -> None

   Register a domain.

   Parameters:
      * **domain** -- A domain class

      * **override** -- If false, do not install it if another domain
        is already installed as the same name If true, unconditionally
        install the domain.

   New in version 1.0.

   Changed in version 1.8: Add *override* keyword.

Sphinx.add_directive_to_domain(domain: str, name: str, cls: type[docutils.parsers.rst.Directive], override: bool = False) -> None

   Register a Docutils directive in a domain.

   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 false, do not install it if another
        directive is already installed as the same name If true,
        unconditionally install the directive.

   New in version 1.0.

   Changed in version 1.8: Add *override* keyword.

Sphinx.add_role_to_domain(domain: str, name: str, role: RoleFunction | XRefRole, override: bool = False) -> None

   Register a Docutils role in a domain.

   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 false, do not install it if another role is
        already installed as the same name If true, unconditionally
        install the role.

   New in version 1.0.

   Changed in version 1.8: Add *override* keyword.

Sphinx.add_index_to_domain(domain: str, index: type[sphinx.domains.Index], override: bool = False) -> None

   Register a custom index for a domain.

   Add a custom *index* class to the domain named *domain*.

   Parameters:
      * **domain** -- The name of the target domain

      * **index** -- The index class

      * **override** -- If false, do not install it if another index
        is already installed as the same name If true, unconditionally
        install the index.

   New in version 1.0.

   Changed in version 1.8: Add *override* keyword.

Sphinx.add_object_type(directivename: str, rolename: str, indextemplate: str = '', parse_node: Callable | None = None, ref_nodeclass: type[TextElement] | None = None, objname: str = '', doc_field_types: list = [], override: bool = False) -> None

   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 "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 Cross-referencing 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.

Sphinx.add_crossref_type(directivename: str, rolename: str, indextemplate: str = '', ref_nodeclass: type[TextElement] | None = None, objname: str = '', override: bool = False) -> None

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

   Parameters:
      **override** -- If false, do not install it if another cross-
      reference type is already installed as the same name If true,
      unconditionally install the cross-reference type.

   Changed in version 1.8: Add *override* keyword.

Sphinx.add_transform(transform: type[docutils.transforms.Transform]) -> None

   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.

   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

Sphinx.add_post_transform(transform: type[docutils.transforms.Transform]) -> None

   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.

   Parameters:
      **transform** -- A transform class

Sphinx.add_js_file(filename: str | None, priority: int = 500, loading_method: str | None = None, **kwargs: Any) -> None

   Register a JavaScript file to include in the HTML output.

   Parameters:
      * **filename** -- The name of a JavaScript file that the default
        HTML template will include. It must be relative to the HTML
        static path, or a full URI with scheme, or "None" . The "None"
        value is used to create an inline "<script>" tag.  See the
        description of *kwargs* below.

      * **priority** -- Files are included in ascending order of
        priority. If multiple JavaScript files have the same priority,
        those files will be included in order of registration. See
        list of "priority range for JavaScript files" below.

      * **loading_method** -- The loading method for the JavaScript
        file. Either "'async'" or "'defer'" are allowed.

      * **kwargs** -- Extra keyword arguments are included as
        attributes of the "<script>" tag.  If the special keyword
        argument "body" is given, its value will be added as the
        content of 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 "html_js_files"                                             |
   +----------------------+----------------------------------------------------------------------------------+

   A JavaScript file can be added to the specific HTML page when an
   extension calls this method on "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.

Sphinx.add_css_file(filename: str, priority: int = 500, **kwargs: Any) -> None

   Register a stylesheet to include in the HTML output.

   Parameters:
      * **filename** -- The name of a CSS file that the default HTML
        template will include. It must be relative to the HTML static
        path, or a full URI with scheme.

      * **priority** -- Files are included in ascending order of
        priority. If multiple CSS files have the same priority, those
        files will be included in order of registration. See list of
        "priority range for CSS files" below.

      * **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 "html_css_files"                                            |
   +----------------------+----------------------------------------------------------------------------------+

   A CSS file can be added to the specific HTML page when an extension
   calls this method on "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.

Sphinx.add_latex_package(packagename: str, options: str | None = None, after_hyperref: bool = False) -> None

   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}

   New in version 1.3.

   New in version 3.1: *after_hyperref* option.

Sphinx.add_lexer(alias: str, lexer: type[pygments.lexer.Lexer]) -> None

   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.

   Changed in version 4.0: Removed support for lexer instances as an
   argument.

Sphinx.add_autodocumenter(cls: Any, override: bool = False) -> None

   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 Developing autodoc extension for IntEnum.

   New in version 0.6.

   Changed in version 2.2: Add *override* keyword.

Sphinx.add_autodoc_attrgetter(typ: type, getter: Callable[[Any, str, Any], Any]) -> None

   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.

Sphinx.add_search_language(cls: Any) -> None

   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
   "html_search_language".

   New in version 1.1.

Sphinx.add_source_suffix(suffix: str, filetype: str, override: bool = False) -> None

   Register a suffix of source files.

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

   Parameters:
      **override** -- If false, do not install it the same suffix is
      already installed. If true, unconditionally install the suffix.

   New in version 1.8.

Sphinx.add_source_parser(parser: type[docutils.parsers.Parser], override: bool = False) -> None

   Register a parser class.

   Parameters:
      **override** -- If false, do not install it if another parser is
      already installed for the same suffix. If true, unconditionally
      install the parser.

   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.

Sphinx.add_env_collector(collector: type[sphinx.environment.collectors.EnvironmentCollector]) -> None

   Register an environment collector class.

   Refer to Environment Collector API.

   New in version 1.6.

Sphinx.add_html_theme(name: str, theme_path: str) -> None

   Register a HTML Theme.

   The *name* is a name of theme, and *theme_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: str, inline_renderers: tuple[Callable | None, Callable | None] | None = None, block_renderers: tuple[Callable | None, Callable | None] | None = None) -> None

   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: str, locale_dir: str) -> None

   Register a message catalog.

   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.

Sphinx.is_parallel_allowed(typ: str) -> bool

   Check whether parallel processing is allowed or not.

   Parameters:
      **typ** -- 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

   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


Sphinx runtime information
==========================

The application object also provides runtime information as
attributes.

Sphinx.project

   Target project.  See "Project".

Sphinx.srcdir

   Source directory.

Sphinx.confdir

   Directory containing "conf.py".

Sphinx.doctreedir

   Directory for storing pickled doctrees.

Sphinx.outdir

   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 "conf.py" 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 based on priority: docutils.document -> docutils.document
            - event.doctree-read(app, doctree) is called in the middle of transforms,
              transforms come before/after this event depending on their priority.

   9. event.env-merge-info(app, env, docnames, other)
      - if running in parallel mode, this event will be emitted for each process

   10. event.env-updated(app, env)
   11. event.env-get-updated(app, env)
   12. event.env-check-consistency(app, env)

   # The updated-docs list can be builder dependent, but generally includes all new/changed documents,
   # plus any output from `env-get-updated`, and then all "parent" documents in the ToC tree
   # For builders that output a single page, they are first joined into a single doctree before post-transforms
   # or the doctree-resolved event is emitted
   for docname in updated-docs:
      13. apply post-transforms (by priority): docutils.document -> docutils.document
      14. event.doctree-resolved(app, doctree, docname)
          - In the event that any reference nodes fail to resolve, the following may emit:
          - event.missing-reference(env, node, contnode)
          - event.warn-missing-reference(domain, node)

   15. Generate output files
   16. event.build-finished(app, exception)

Here is a more detailed list of these events.

builder-inited(app)

   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.

   Parameters:
      * **env** -- The build environment ("app.builder.env").

      * **node** -- The "pending_xref" node to be resolved. Its
        "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.

warn-missing-reference(app, domain, node)

   Emitted when a cross-reference to an object cannot be resolved even
   after "missing-reference".  If the event handler can emit warnings
   for the missing reference, it should return "True". The
   configuration variables "nitpick_ignore" and "nitpick_ignore_regex"
   prevent the event from being emitted for the corresponding nodes.

   New in version 3.4.

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 after reading all documents, when 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

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.

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

   Note:

     You can install JS/CSS files for the specific page via
     "Sphinx.add_js_file()" and "Sphinx.add_css_file()" since v3.5.0.

   New in version 0.4.

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

linkcheck-process-uri(app, uri)

   Emitted when the linkcheck builder collects hyperlinks from
   document.  *uri* is a collected URI.  The event handlers can modify
   the URI by returning a string.

   New in version 4.1.

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 = (7, 1, 2, 'final', 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] = {})

   Configuration file abstraction.

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

   It is exposed via the "Sphinx"".config" and
   "sphinx.environment.BuildEnvironment"".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

   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: Theme | None = None, dirs: list[str] | None = None) -> 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() -> float

      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

      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

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


Exceptions
==========

exception sphinx.errors.SphinxError

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

   category

      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

   Configuration error.

exception sphinx.errors.ExtensionError(message: str, orig_exc: Exception | None = None, modname: str | None = None)

   Extension error.

exception sphinx.errors.ThemeError

   Theme error.

exception sphinx.errors.VersionRequirementError

   Incompatible Sphinx version error.
