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
standard-imghdr==3.10.14; python_version >= "3.13"

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)

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)

Document the given configuration value.

Parameters

var_obj (Type[ConfigVar])

Return type

paragraph

run()

Process the content of the directive.

Return type

Sequence[Node]

parse_conf_node(env, text, node)

Parse the content of a conf directive.

Parameters

• env (BuildEnvironment) – The Sphinx build environment.

• text (str) – The content of the directive.

• node (desc_signature) – The docutils node class.

Return type

str

setup(app)

Setup Sphinx Extension.

Parameters

app (Sphinx) – The Sphinx app

Return type

Dict[str, Any]