plasmapy_sphinx.directives.event
Functionality for declaring and cross-referencing
Sphinx events.
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
sphinx.application.Sphinx.add_event
.
The code contained in this module was taken and adapted from the conf.py
file
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_mapping
configuration value with thesphinx.ext.intersphinx
extension.The directive is used like…
.. event:: name (signature) Event documentation.
wherename
is the event name andsignature
represents what the connected function’s signature should look like.Example
The following example illustrates how to document the
dummy-event
event... 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)
- Parameters:
app – Instance of the Sphinx applications.
node – The pending node to be resolved.
This is just a dummy event for demonstration purposes.
- :event:
This role is provided for easy cross-linking to an event’s definition. For example, doing
:event:`dummy-event`
will cross-link to thedummy-event
definition likedummy-event
. Or, a link to Sphinx’sbuilder-inited
event goes like:event:`builder-inited`
->builder-inited
.Linking to external packages is made possible when using
sphinx.ext.intersphinx
.
API
Functions
|
Used to set up the |
|
A |