Functionality for declaring and cross-referencing Sphinx configuration values. Configuration values are variables that can be defined in the file to control the default behavior for Sphinx and extension packages like plasmapy_sphinx. This code was taken and adapted from the 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.


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

The code renders like…





This is an example documentation for the configuration value dummy_value.


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.




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