plasmapy_sphinx.directives.confval

Functionality for declaring and cross-referencing Sphinx configuration values. Configuration values are variables that can be defined in the conf.py file to control the default behavior for Sphinx and extension packages like plasmapy_sphinx. This code was taken and adapted from the conf.py files of the sphinx and sphinx_rtd_theme packages.

.. confval:: name

A directive used for documenting Sphinx configuration values. While this directive is not provided by Sphinx, it is used by Sphinx and, thus, cross-linking is provided through the intersphinx_mapping configuration value with the sphinx.ext.intersphinx extension.

Optional Fields

:type: (string)

An optional flag that specifies the configuration value’s data type.

:default: (string)

An optional flag that specifies the default value for the configuration value.

Example

The following example illustrates how to document the dummy_value configuration value.

.. confval:: dummy_value

   :type: `bool`
   :default: `True`

   This is an example documentation for the configuration value
   ``dummy_value``.

The code renders like…

dummy_value

Type:

bool

Default:

True

This is an example documentation for the configuration value dummy_value.

:confval:

This role is provided for easy cross-linking to a configuration value’s definition. For example, doing :confval:`dummy_value` will cross-link to the dummy_value configuration value like dummy_value. Or, a link to Sphinx’s intersphinx_mapping configuration value goes like :confval:`intersphinx_mapping` -> intersphinx_mapping.

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

API

Functions

setup(app)

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