mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
474 lines
15 KiB
ReStructuredText
474 lines
15 KiB
ReStructuredText
.. 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
|