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.
- setup(app)[source]¶
Setup
sphinx_toolbox.confval
.New in version 0.7.0.
- Parameters
app (
Sphinx
) – The Sphinx application.- Return type