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.
This application object has the public API described in the following.
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.
Producing messages / logging
The application object also provides support for emitting leveled messages.
There is no "error" call: in Sphinx, errors are defined as things that stop the build; just raise an exception (:exc:`sphinx.errors.SphinxError` or a custom subclass) to do that.
Sphinx core events
These events are known to the core. The arguments shown are given to the registered event handlers. Use :meth:`.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)
Checking the Sphinx version
Use this to adapt your extension to API changes in Sphinx.
The Config object
The config object makes the values of all config values available as attributes.
It is available as the config attribute on the application and environment objects. For example, to get the value of :confval:`language`, use either app.config.language or env.config.language.