confval
¶
The confval directive and role for configuration values.
Enable sphinx_toolbox.confval
by adding the following
to the extensions
variable in your conf.py
:
extensions = [
...
'sphinx_toolbox.confval',
]
For more information see https://www.sphinx-doc.org/en/master/usage/extensions#third-party-extensions .
Usage¶
-
.. confval::
name¶ Used to document a configuration value.
-
:type:
(string)¶ Indicates the configuration value’s type.
-
:required:
(flag)¶ Indicates the whether the configuration value is required.
-
:default:
(string)¶ Indicates the default value.
-
:noindex:
(flag)¶ Disables the index entry and cross-referencing for this configuration value.
New in version 2.11.0.
-
Examples:
.. confval:: demo
:type: string
:default: ``"Hello World"``
:required: False
-
demo
¶ - Type: stringRequired:
False
Default:"Hello World"
To enable this feature set the :confval:`demo` configuration value to "True".
To enable this feature set the demo
configuration value to “True”.
API Reference¶
Classes:
|
The confval directive. |
Functions:
|
Create and register the |
|
Setup |
-
class
ConfigurationValue
(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶ Bases:
GenericObject
The confval directive.
Changed in version 1.1.0: The formatting of the type, required and default options can be customised using the
self.format_*
methods.Changed in version 2.11.0: Added the
:noindex:
option, which disables the index entry and cross-referencing for this configuration value.Methods:
run
()Process the content of the directive.
format_type
(the_type)Formats the
:type:
option.format_required
(required)Formats the
:required:
option.format_default
(default)Formats the
:default:
option.-
option_spec
= {'default': <function unchanged_required>, 'noindex': <function flag>, 'required': <function unchanged_required>, 'type': <function unchanged_required>}¶
-
-
setup
(app)[source]¶ Setup
sphinx_toolbox.confval
.New in version 0.7.0.
- Parameters:
app (
Sphinx
) – The Sphinx application.- Return type: