Functionality for declaring and cross-referencing
Sphinx events occur at specific points in the Sphinx build. When an event
is reached a signal is emitted with
sphinx.application.Sphinx.emit that causes
the build to “pause” and allow any connected functionality to do the desired
processing. New functionality can be connected to an event with
sphinx.application.Sphinx.connect and new events can be created using
The code contained in this module was taken and adapted from the
of Sphinx’s documentation.
- .. event:: name (signature)¶
A directive used for documenting Sphinx events. While this directive is not provided by Sphinx, it is usd by Sphinx and, thus, cross-linking is provided through the
intersphinx_mappingconfiguration value with the
The directive is used like…
.. event:: name (signature) Event documentation.where
nameis the event name and
signaturerepresents what the connected function’s signature should look like.
The following example illustrates how to document the
.. event:: dummy-event (app, node) :param app: Instance of the Sphinx applications. :param node: The pending node to be resolved. This is just a dummy event for demonstration purposes.
The code renders like…
- dummy-event(app, node)¶
app – Instance of the Sphinx applications.
node – The pending node to be resolved.
This is just a dummy event for demonstration purposes.
This role is provided for easy cross-linking to an event’s definition. For example, doing
:event:`dummy-event`will cross-link to the
dummy-event. Or, a link to Sphinx’s
builder-initedevent goes like
Linking to external packages is made possible when using