Each Sphinx extension is a Python module with at least a setup() function. This function is called at initialization time with one argument, the application object representing the Sphinx process. This application object has the following public API:
Register a Docutils directive. name must be the prospective directive name, func the directive function for details about the signature and return value. content, arguments and options are set as attributes on the function and determine whether the directive has content, arguments and options, respectively. For their exact meaning, please consult the Docutils documentation.
This method is a very convenient way to add a new type of information that can be cross-referenced. It will do this:
For example, if you have this call in a custom Sphinx extension:
app.add_description_unit('directive', 'dir', 'pair: %s; directive')
you can use this markup in your documents:
.. directive:: function Document a function. <...> See also the :dir:`function` directive.
For the directive, an index entry will be generated as if you had prepended
.. index:: pair: function; directive
The reference node will be of class literal (so it will be rendered in a proportional font, as appropriate for code) unless you give the ref_nodeclass argument, which must be a docutils node class (most useful are docutils.nodes.emphasis or docutils.nodes.strong – you can also use docutils.nodes.generated if you want no further text decoration).
For the role content, you have the same options as for standard Sphinx roles (see Cross-referencing syntax).
This method is very similar to add_description_unit() except that the directive it generates must be empty, and will produce no output.
That means that you can add semantic targets to your sources, and refer to them using custom roles instead of generic ones (like ref). Example call:
app.add_crossref_type('topic', 'topic', 'single: %s', docutils.nodes.emphasis)
Example usage:
.. topic:: application API The application API ------------------- <...> See also :topic:`this section <application API>`.
(Of course, the element following the topic directive needn’t be a section.)
Register callback to be called when event is emitted. For details on available core events and the arguments of callback functions, please see Sphinx core events.
The method returns a “listener ID” that can be used as an argument to disconnect().
Examples of using the Sphinx extension API can be seen in the sphinx.ext package.
These events are known to the core:
Event name | Emitted when | Arguments |
---|---|---|
'builder-inited' | the builder object has been created | -none- |
'doctree-read' | a doctree has been parsed and read by the environment, and is about to be pickled | doctree |
'doctree-resolved' | a doctree has been “resolved” by the environment, that is, all references and TOCs have been inserted | doctree, docname |
This class defines the interface for a “template bridge”, that is, a class that renders templates given a template name and a context.