path: root/doc/extdev/appapi.rst

.. highlight:: rest

Application API
===============

.. module:: sphinx.application
   :synopsis: Application class and extensibility interface.


Each Sphinx extension is a Python module with at least a :func:`setup`
function.  This function is called at initialization time with one argument,
the application object representing the Sphinx process.

.. class:: 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 :mod:`sphinx.ext`
package.

.. currentmodule:: sphinx.application

.. automethod:: Sphinx.setup_extension

.. automethod:: Sphinx.require_sphinx

.. automethod:: Sphinx.connect

.. automethod:: Sphinx.disconnect

.. automethod:: Sphinx.add_builder

.. automethod:: Sphinx.add_config_value

.. automethod:: Sphinx.add_event

.. automethod:: Sphinx.set_translator

.. automethod:: Sphinx.add_node

.. automethod:: Sphinx.add_enumerable_node

.. automethod:: Sphinx.add_directive

.. automethod:: Sphinx.add_role

.. automethod:: Sphinx.add_generic_role

.. automethod:: Sphinx.add_domain

.. automethod:: Sphinx.add_directive_to_domain

.. automethod:: Sphinx.add_role_to_domain

.. automethod:: Sphinx.add_index_to_domain

.. automethod:: Sphinx.add_object_type

.. automethod:: Sphinx.add_crossref_type

.. automethod:: Sphinx.add_transform

.. automethod:: Sphinx.add_post_transform

.. automethod:: Sphinx.add_js_file

.. automethod:: Sphinx.add_css_file

.. automethod:: Sphinx.add_latex_package

.. automethod:: Sphinx.add_lexer

.. automethod:: Sphinx.add_autodocumenter

.. automethod:: Sphinx.add_autodoc_attrgetter

.. automethod:: Sphinx.add_search_language

.. automethod:: Sphinx.add_source_suffix

.. automethod:: Sphinx.add_source_parser

.. automethod:: Sphinx.add_env_collector

.. automethod:: Sphinx.add_html_theme

.. automethod:: Sphinx.add_html_math_renderer

.. automethod:: Sphinx.add_message_catalog

.. automethod:: Sphinx.is_parallel_allowed

.. exception:: ExtensionError

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


Emitting events
---------------

.. class:: Sphinx
   :no-index:

   .. automethod:: emit

   .. automethod:: emit_firstresult


Sphinx runtime information
--------------------------

The application object also provides runtime information as attributes.

.. attribute:: Sphinx.project

   Target project.  See :class:`.Project`.

.. attribute:: Sphinx.srcdir

   Source directory.

.. attribute:: Sphinx.confdir

   Directory containing ``conf.py``.

.. attribute:: Sphinx.doctreedir

   Directory for storing pickled doctrees.

.. attribute:: Sphinx.outdir

   Directory for storing built document.


.. _events:

Sphinx core events
------------------

These events are known to the core.  The arguments shown are given to the
registered event handlers.  Use :meth:`.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:

.. code-block:: python

   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:

.. code-block:: none

   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.

.. event:: builder-inited (app)

   Emitted when the builder object has been created.  It is available as
   ``app.builder``.

.. event:: config-inited (app, config)

   Emitted when the config object has been initialized.

   .. versionadded:: 1.8

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

   .. versionadded:: 1.1

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

   .. versionadded:: 0.5

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

   .. versionadded:: 1.3

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

   .. versionadded:: 0.5

.. event:: include-read (app, relative_path, parent_docname, content)

   Emitted when a file has been read with the :dudir:`include` directive.
   The *relative_path* argument is a :py:class:`~pathlib.Path` object representing
   the relative path of the included file from the :term:`source directory`.
   The *parent_docname* argument is the name of the document that
   contains the :dudir:`include` directive.
   The *source* argument is a list whose single element is
   the contents of the included file.
   You can process the contents and replace this item
   to transform the included content,
   as with the :event:`source-read` event.

   .. versionadded:: 7.2.5

   .. seealso:: The :dudir:`include` directive and the :event:`source-read` event.

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

   .. versionadded:: 2.4

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

.. event:: 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 :class:`~nodes.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 :class:`~sphinx.errors.NoUri` to prevent other handlers in
   trying and suppress a warning about this cross-reference being unresolved.

   :param env: The build environment (``app.builder.env``).
   :param node: The :class:`~sphinx.addnodes.pending_xref` node to be resolved.
      Its ``reftype``, ``reftarget``, ``modname`` and ``classname`` attributes
      determine the type and target of the reference.
   :param contnode: The node that carries the text and formatting inside the
      future reference and should be a child of the returned reference node.

   .. versionadded:: 0.5

.. event:: warn-missing-reference (app, domain, node)

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

   .. versionadded:: 3.4

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

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

   .. versionadded:: 1.3

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

   .. versionadded:: 0.5

   .. versionchanged:: 1.3
      The handlers' return value is now used.

.. event:: env-check-consistency (app, env)

   Emitted when Consistency checks phase.  You can check consistency of
   metadata for whole of documents.

   .. versionadded:: 1.6

      As a **experimental** event

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

   .. versionadded:: 1.0

.. event:: 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
             :meth:`Sphinx.add_js_file` and :meth:`Sphinx.add_css_file` since
             v3.5.0.

   .. versionadded:: 0.4

   .. versionchanged:: 1.3
      The return value can now specify a template name.

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

   .. versionadded:: 4.1

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

   .. versionadded:: 0.5


Checking the Sphinx version
---------------------------

.. currentmodule:: sphinx

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

.. autodata:: version_info


The Config object
-----------------

.. currentmodule:: sphinx.config

.. autoclass:: Config


.. _template-bridge:

The template bridge
-------------------

.. currentmodule:: sphinx.application

.. autoclass:: TemplateBridge
   :members:


.. _exceptions:

Exceptions
----------

.. module:: sphinx.errors

.. autoexception:: SphinxError

.. autoexception:: ConfigError

.. autoexception:: ExtensionError

.. autoexception:: ThemeError

.. autoexception:: VersionRequirementError