sphinx-autodoc-sphinx¶

Alpha GitHub PyPI

Experimental Sphinx extension for documenting config values registered by extension setup() hooks. It takes the repetitive part of conf.py reference-writing, records sphinx:~sphinx.application.Sphinx.add_config_value() calls, and renders them as live confval entries and summary indexes.

$ pip install sphinx-autodoc-sphinx

Downstream `conf.py`¶

extensions = ["sphinx_autodoc_sphinx"]

Working usage examples¶

Render one config value:

```{eval-rst}
.. autoconfigvalue:: sphinx_fonts.sphinx_font_preload
```

Render every config value from an extension module:

```{eval-rst}
.. autoconfigvalue-index:: sphinx_config_demo
```

Live demos¶

This page also uses sphinx-autodoc-docutils to document the config-doc directives themselves, so the page demonstrates both config-value output and directive documentation.

Index a demo extension’s config surface¶

Config Value Index

Name	Type	Default	Rebuild
`demo_theme_accent`	`dict`	`{'light': 'mint', 'dark': 'teal'}`	`html`
`demo_show_callouts`	`bool`	`True`	`html`

Render a single demo config value¶

demo_debug

Type:: bool
Default:: False

Registered by sphinx_config_single_demo.setup().

Rebuild: env.

Bulk config values demo¶

Renders all config values from a module at once:

demo_theme_accent¶

Type:: dict
Default:: {'light': 'mint', 'dark': 'teal'}

Registered by sphinx_config_demo.setup().

Rebuild: html.

demo_show_callouts¶

Type:: bool
Default:: True

Registered by sphinx_config_demo.setup().

Rebuild: html.

Document the extension’s own directive helper¶

.. autoconfigvalue::

Render one config value from a fully-qualified module.option path.

Python path: sphinx_autodoc_sphinx._directives.AutoconfigvalueDirective

Required arguments: 1

Optional arguments: 0

Final argument whitespace: False

Has content: False

Options:

:no-index:: Validator: flag.

The extension itself registers documentation directives rather than new roles or config values. The generated package reference below lists its registered surface from the live setup() calls.

Copyable config snippet

extensions = [
    "sphinx_autodoc_sphinx",
]

Package metadata

Source on GitHub: sphinx-autodoc-sphinx
PyPI: sphinx-autodoc-sphinx
Maturity: Alpha

Registered Surface

sphinx_autodoc_sphinx

Directives

Name	Kind	Callable	Summary
`autoconfigvalue`	directive	`AutoconfigvalueDirective`	Render one config value from a fully-qualified `module.option` path.
`autoconfigvalues`	directive	`AutoconfigvaluesDirective`	Render all config values registered by one extension module.
`autoconfigvalue-index`	directive	`AutoconfigvalueIndexDirective`	Render a summary table for a module’s config values.
`autosphinxconfig-index`	directive	`AutosphinxconfigIndexDirective`	Render a drop-in index plus detailed `confval` blocks.

autoconfigvalue options

Option
`:no-index:`	Registered option

autoconfigvalues options

Option
`:no-index:`	Registered option

Source on GitHub · PyPI