fix(docs[redirects]): remove cli.md self-redirect for dirhtml, revert suppress_warnings

tony · tony · commit d288c8b2ea85 · 2026-03-23T19:51:32.000-05:00
why: cli.md → commands/index.md → cli/index.md chain produces same
dirhtml output path (cli/index.html) as the real cli/index.md file.
Rediraffe reports "already exists" and exits with code 1.
what:
- Comment out cli.md redirect (same dirhtml output as cli/index.md)
- Revert docutils suppress_warnings (didn't help, wrong approach)
diff --git a/docs/conf.py b/docs/conf.py
@@ -128,9 +128,6 @@
 # (types in TYPE_CHECKING blocks used for circular import avoidance)
 suppress_warnings = [
     "sphinx_autodoc_typehints.forward_reference",
-    # dirhtml builder creates duplicate implicit labels across CLI pages
-    # (each argparse page generates "Usage", "Options", "Examples" headings)
-    "docutils",
 ]
 
 # sphinxext.opengraph
diff --git a/docs/redirects.txt b/docs/redirects.txt
@@ -1,4 +1,4 @@
-"cli.md" "commands/index.md"
+# "cli.md" → commands/index.md → cli/index.md: not needed with dirhtml (same output path)
 # "api.md" → api/index.md: not needed with dirhtml (same output path as api/index.md redirect)
 "examples.md" "configuration/examples.md"
 "plugin_system.md" "plugins/index.md"

Original file line number	Diff line number	Diff line change
`@@ -128,9 +128,6 @@`
`128`	`128`	`# (types in TYPE_CHECKING blocks used for circular import avoidance)`
`129`	`129`	`suppress_warnings = [`
`130`	`130`	`"sphinx_autodoc_typehints.forward_reference",`
`131`		`- # dirhtml builder creates duplicate implicit labels across CLI pages`
`132`		`- # (each argparse page generates "Usage", "Options", "Examples" headings)`
`133`		`- "docutils",`
`134`	`131`	`]`
`135`	`132`
`136`	`133`	`# sphinxext.opengraph`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-"cli.md" "commands/index.md"`
	`1`	`+# "cli.md" → commands/index.md → cli/index.md: not needed with dirhtml (same output path)`
`2`	`2`	`# "api.md" → api/index.md: not needed with dirhtml (same output path as api/index.md redirect)`
`3`	`3`	`"examples.md" "configuration/examples.md"`
`4`	`4`	`"plugin_system.md" "plugins/index.md"`