configconfig.autoconfig

A Sphinx directive for documenting YAML configuration values.

Provides the autoconfig directive to document configuration values automatically, the conf directive to document them manually, and the conf role to link to a conf directive.

Attention

This module has the following additional requirements:

docutils
sphinx<3.4.0,>=3.0.3
sphinx-toolbox

These can be installed as follows:

python -m pip install configconfig[sphinx]

Usage

.. autoconfig::

Directive to automatically document an YAML configuration value.

Takes a single argument, either the fully qualified name of the ConfigVar object, or the name of the module if the :category: option is given.

:category: (string)

(optional) The category of options to document.

.. conf::

Directive to document an YAML configuration value.

:conf:

Role to add a cross-reference to a conf or autoconfig directive.

API Reference

Classes:

AutoConfigDirective(name, arguments, …)

Sphinx directive to automatically document an YAML configuration value.

Functions:

parse_conf_node(env, text, node)

Parse the content of a conf directive.

setup(app)

Setup Sphinx Extension.
class AutoConfigDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Bases: SphinxDirective

Sphinx directive to automatically document an YAML configuration value.

Methods:

document_config_var(var_obj)

Document the given configuration value.

run()

Process the content of the directive.
document_config_var(var_obj)[source]

Document the given configuration value.

Parameters:

var_obj (Type[ConfigVar])

Return type:

paragraph

run()[source]

Process the content of the directive.

Return type:

Sequence[Node]

parse_conf_node(env, text, node)[source]

Parse the content of a conf directive.

Parameters:
Return type:

str

setup(app)[source]

Setup Sphinx Extension.

Parameters:

app (Sphinx) – The Sphinx app

Return type:

Dict[str, Any]