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 thesphinx.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…
- :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 thedummy_value
configuration value likedummy_value
. Or, a link to Sphinx’sintersphinx_mapping
configuration value goes like:confval:`intersphinx_mapping`
->intersphinx_mapping
.Linking to external packages is made possible when using
sphinx.ext.intersphinx
.
API
Functions
|
A |