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.

:confval:

Role which provides a cross-reference to a confval directive.

Examples:

.. confval:: demo
    :type: string
    :default: ``"Hello World"``
    :required: False
demo
Type: string
Required: 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:

ConfigurationValue(name, arguments, options, …)

The confval directive.

Functions:

register_confval(app[, override])

Create and register the confval role and directive.

setup(app)

Setup sphinx_toolbox.confval.

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.

run()[source]

Process the content of the directive.

Return type

List[Node]

static format_type(the_type)[source]

Formats the :type: option.

New in version 1.1.0.

Parameters

the_type (str)

Return type

str

static format_required(required)[source]

Formats the :required: option.

New in version 1.1.0.

Parameters

required (str)

Return type

bool

static format_default(default)[source]

Formats the :default: option.

New in version 1.1.0.

Parameters

default (str)

Return type

str

register_confval(app, override=False)[source]

Create and register the confval role and directive.

Parameters
  • app (Sphinx) – The Sphinx application.

  • override (bool) – Default False.

setup(app)[source]

Setup sphinx_toolbox.confval.

New in version 0.7.0.

Parameters

app (Sphinx) – The Sphinx application.

Return type

SphinxExtMetadata