Source

sphinx / doc / extdev / appapi.rst

Full commit

Application API

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.

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.

Emitting events

Producing messages / logging

The application object also provides support for emitting leveled messages.

Note

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.

The template bridge

Exceptions