mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
111 lines
4.2 KiB
ReStructuredText
111 lines
4.2 KiB
ReStructuredText
.. _extensions:
|
|
|
|
Sphinx Extensions
|
|
=================
|
|
|
|
.. module:: sphinx.application
|
|
:synopsis: Application class and extensibility interface.
|
|
|
|
Since many projects will need special features in their documentation, Sphinx is
|
|
designed to be extensible on several levels.
|
|
|
|
First, you can add new :term:`builder`\s to support new output formats or
|
|
actions on the parsed documents. Then, it is possible to register custom
|
|
reStructuredText roles and directives, extending the markup. And finally, there
|
|
are so-called "hook points" at strategic places throughout the build process,
|
|
where an extension can register a hook and run specialized code.
|
|
|
|
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 following public API:
|
|
|
|
.. method:: Application.add_builder(builder)
|
|
|
|
Register a new builder. *builder* must be a class that inherits from
|
|
:class:`~sphinx.builder.Builder`.
|
|
|
|
.. method:: Application.add_config_value(name, default, rebuild_env)
|
|
|
|
Register a configuration value. This is necessary for Sphinx to recognize
|
|
new values and set default values accordingly. The *name* should be prefixed
|
|
with the extension name, to avoid clashes. The *default* value can be any
|
|
Python object. The boolean value *rebuild_env* must be ``True`` if a change
|
|
in the setting only takes effect when a document is parsed -- this means that
|
|
the whole environment must be rebuilt.
|
|
|
|
.. method:: Application.add_event(name)
|
|
|
|
Register an event called *name*.
|
|
|
|
.. method:: Application.add_node(node)
|
|
|
|
Register a Docutils node class. This is necessary for Docutils internals.
|
|
It may also be used in the future to validate nodes in the parsed documents.
|
|
|
|
.. method:: Application.add_directive(name, cls, content, arguments, **options)
|
|
|
|
Register a Docutils directive. *name* must be the prospective directive
|
|
name, *func* the directive function (see the Docutils documentation - XXX
|
|
ref) 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.
|
|
|
|
.. method:: Application.add_role(name, role)
|
|
|
|
Register a Docutils role. *name* must be the role name that occurs in the
|
|
source, *role* the role function (see the Docutils documentation on details).
|
|
|
|
.. method:: Application.add_description_unit(directivename, rolename, indexdesc='', parse_node=None)
|
|
|
|
XXX
|
|
|
|
.. method:: Application.connect(event, callback)
|
|
|
|
Register *callback* to be called when *event* is emitted. For details on
|
|
available core events and the arguments of callback functions, please see
|
|
:ref:`events`.
|
|
|
|
The method returns a "listener ID" that can be used as an argument to
|
|
:meth:`disconnect`.
|
|
|
|
.. method:: Application.disconnect(listener_id)
|
|
|
|
Unregister callback *listener_id*.
|
|
|
|
.. method:: Application.emit(event, *arguments)
|
|
|
|
Emit *event* and pass *arguments* to the callback functions. Do not emit
|
|
core Sphinx events in extensions!
|
|
|
|
|
|
.. exception:: ExtensionError
|
|
|
|
All these functions raise this exception if something went wrong with the
|
|
extension API.
|
|
|
|
Examples of using the Sphinx extension API can be seen in the :mod:`sphinx.ext`
|
|
package.
|
|
|
|
|
|
.. _events:
|
|
|
|
Sphinx core events
|
|
------------------
|
|
|
|
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 *doctree*
|
|
by the environment, and is about to
|
|
be pickled
|
|
``'doctree-resolved'`` a doctree has been "resolved" by *doctree*, *docname*
|
|
the environment, that is, all
|
|
references and TOCs have been
|
|
inserted
|
|
====================== =================================== =========
|