Source code for plasmapy_sphinx.directives.confval

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.

.. rst:directive:: .. 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 :confval:`intersphinx_mapping`
      configuration value with the `sphinx.ext.intersphinx` extension.

    .. rubric:: Optional Fields

    .. rst:directive:option:: type
       :type: string

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

    .. rst:directive:option:: default
       :type: string

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

    .. rubric:: Example

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

    .. code-block:: rst

        .. confval:: dummy_value

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

           This is an example documentation for the configuration value

    The code renders like...

    .. confval:: dummy_value

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

       This is an example documentation for the configuration value

.. rst:role:: 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 :confval:`dummy_value`.  Or,
    a link to Sphinx's ``intersphinx_mapping`` configuration value goes like
    ``:confval:`intersphinx_mapping``` -> :confval:`intersphinx_mapping`.

    *Linking to external packages is made possible when using*

from sphinx.application import Sphinx
from import PyField
from sphinx.locale import _
from sphinx.util.docfields import Field

[docs] def setup(app: Sphinx) -> None: """ A `sphinx` ``setup()`` function setting up the :rst:dir:`confval` directive and :rst:role:`confval` role. """ # this was taken from the sphinx and sphinx_rtd_theme files and creates # the documenting directive `.. confval::` and role `:confval:` for documenting # sphinx configuration variables app.add_object_type( directivename="confval", rolename="confval", objname="configuration value", indextemplate="pair: %s; configuration value", doc_field_types=[ PyField( name="type", names=("type",), label=_("Type"), has_arg=False, bodyrolename="class", ), Field( name="default", names=("default",), label=_("Default"), has_arg=False, ), ], )