Skip to content

Commit 08c1c74

Browse files
committed
feat(sphinx-autodoc-sphinx): add :exclude: option to autoconfigvalues
why: two extensions (sphinx-gp-sitemap and sphinx-gp-llms) both register site_url via app.add_config_value(). The autoconfigvalues directive on both reference pages emits duplicate confval entries, which Sphinx's RST domain warns about — breaking CI's -W build. what: - Add :exclude: option to AutoconfigvaluesDirective that accepts a comma/whitespace-separated list of config value names to skip - Add _parse_exclude() helper with doctests - Use :exclude: site_url on sphinx-gp-llms reference page - Document the option in sphinx-autodoc-sphinx tutorial
1 parent 534f595 commit 08c1c74

3 files changed

Lines changed: 34 additions & 1 deletion

File tree

docs/packages/sphinx-autodoc-sphinx/tutorial.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,13 @@ Render every config value from an extension module:
1919
.. autoconfigvalues:: sphinx_config_demo
2020
```
2121
````
22+
23+
Exclude specific config values (useful when two extensions register
24+
the same value and Sphinx warns on the duplicate ``confval``):
25+
26+
````myst
27+
```{eval-rst}
28+
.. autoconfigvalues:: sphinx_gp_llms
29+
:exclude: site_url
30+
```
31+
````

docs/packages/sphinx-gp-llms/reference.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,4 +9,5 @@ Generated from `app.add_config_value()` registrations in
99

1010
```{eval-rst}
1111
.. autoconfigvalues:: sphinx_gp_llms
12+
:exclude: site_url
1213
```

packages/sphinx-autodoc-sphinx/src/sphinx_autodoc_sphinx/_directives.py

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -434,18 +434,40 @@ def run(self) -> list[nodes.Node]:
434434
)
435435

436436

437+
def _parse_exclude(raw: str) -> frozenset[str]:
438+
"""Parse a comma/whitespace-separated list of config value names.
439+
440+
Examples
441+
--------
442+
>>> sorted(_parse_exclude("site_url, html_baseurl"))
443+
['html_baseurl', 'site_url']
444+
445+
>>> _parse_exclude("")
446+
frozenset()
447+
"""
448+
return frozenset(
449+
name.strip() for name in raw.replace(",", " ").split() if name.strip()
450+
)
451+
452+
437453
class AutoconfigvaluesDirective(SphinxDirective):
438454
"""Render all config values registered by one extension module."""
439455

440456
required_arguments = 1
441457
has_content = False
442-
option_spec: t.ClassVar[OptionSpec] = {"no-index": directives.flag}
458+
option_spec: t.ClassVar[OptionSpec] = {
459+
"no-index": directives.flag,
460+
"exclude": directives.unchanged,
461+
}
443462

444463
def run(self) -> list[nodes.Node]:
445464
module_name = self.arguments[0]
446465
no_index = "no-index" in self.options
466+
exclude = _parse_exclude(self.options.get("exclude", ""))
447467
result: list[nodes.Node] = []
448468
for value in discover_config_values(module_name):
469+
if value.name in exclude:
470+
continue
449471
result.extend(
450472
_render_config_value_nodes(self, value, no_index=no_index),
451473
)

0 commit comments

Comments
 (0)