Event callbacks API — Sphinx documentation

Connecting callback functions to events is a simple way to extend Sphinx, by hooking into the build process at various points.
Use Sphinx.connect() in an extension’s setup function, or a setup function in your project’s conf.py, to connect functions to the events:
Extensions can add their own events by using Sphinx.add_event(), and calling them them with EventManager.emit() or EventManager.emit_firstresult().
Many events pass a doctree to their callbacks. See the glossary entry for where its node types are documented.
Below is an overview of the core event that happens during a build.
Here is also a flow diagram of the events, within the context of the Sphinx build process:
Sphinx core events flow¶
Here is a more detailed list of these events.
Emitted when the config object has been initialized.
Added in version 1.8.
Emitted when the builder object has been created (available as app.builder).
env – BuildEnvironment
Sequence[str] of additional docnames to re-read
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.
Added in version 1.1.
env – BuildEnvironment
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.
Added in version 0.5.
env – BuildEnvironment
docnames – list[str]
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 found_docs).
You can also remove document names; do this with caution since it will make Sphinx treat changed files as unchanged.
Added in version 1.3.
content – list[str] with a single element, representing the content of the source file.
Emitted when a source file has been read.
You can process the content 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:`...`.
Added in version 0.5.
relative_path – Path representing the included file relative to the source directory.
parent_docname – str of the document name that contains the include directive.
content – list[str] with a single element, representing the content of the included file.
Emitted when a file has been read with the include directive.
You can process the content and replace this item to transform the included content, as with the source-read event.
Added in version 7.2.5.
The include directive and the source-read event.
contentnode – desc_content
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.
Added in version 2.4.
doctree – docutils.nodes.document