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 the sphinx.ext.intersphinx extension.

The directive is used like…

.. event:: name (signature)

   Event documentation.
where name is the event name and signature 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 the dummy-event definition like dummy-event. Or, a link to Sphinx’s builder-inited event goes like :event:`builder-inited` -> builder-inited.

Linking to external packages is made possible when using sphinx.ext.intersphinx.

API

Functions

parse_event(env, sig, signode)

Used to set up the event directive and role for documenting Sphinx events.

setup(app)

A sphinx setup() function setting up the event directive and event role.