🐛 fix(prog): propagate :prog: override to subcommands

When using the :prog: directive option to rename the program, only the
top-level parser prog was updated. Subcommand parsers still retained the
original prog, producing inconsistent titles and references.

Recursively updates all subparser prog values when :prog: is set.

Fixes #71

Author: gaborbernat

roots/test-prog-subcommands/conf.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+extensions = ["sphinx_argparse_cli"]
+nitpicky = True

roots/test-prog-subcommands/index.rst

@@ -0,0 +1,4 @@
+.. sphinx_argparse_cli::
+  :module: parser
+  :func: make
+  :prog: my-tool

roots/test-prog-subcommands/parser.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser
+
+
+def make() -> ArgumentParser:
+    parser = ArgumentParser(prog="original-name")
+    sub = parser.add_subparsers()
+    sub.add_parser("foo", help="foo help")
+    return parser

src/sphinx_argparse_cli/_logic.py

@@ -140,7 +140,9 @@ def parser(self) -> ArgumentParser:
                 raise self.error(msg)
 
             if "prog" in self.options:
-                self._parser.prog = self.options["prog"]
+                old_prog, new_prog = self._parser.prog, self.options["prog"]
+                self._parser.prog = new_prog
+                _update_sub_parser_prog(self._parser, old_prog, new_prog)
 
             self._raw_format = self._parser.formatter_class == RawDescriptionHelpFormatter
         return self._parser
@@ -447,6 +449,15 @@ def _strip_ansi_colors(text: str) -> str:  # pragma: >=3.14 cover
     return _ANSI_COLOR_RE.sub("", text)
 
 
+def _update_sub_parser_prog(parser: ArgumentParser, old_prog: str, new_prog: str) -> None:
+    if not (sub_parsers := parser._subparsers):  # noqa: SLF001
+        return
+    sub_action: _SubParsersAction[ArgumentParser] = sub_parsers._group_actions[0]  # type: ignore[assignment]  # noqa: SLF001
+    for sub_parser in sub_action.choices.values():
+        sub_parser.prog = sub_parser.prog.replace(old_prog, new_prog, 1)
+        _update_sub_parser_prog(sub_parser, old_prog, new_prog)
+
+
 __all__ = [
     "SphinxArgparseCli",
 ]

tests/test_logic.py

@@ -381,3 +381,10 @@ def test_actions(build_outcome: str) -> None:
     assert "increase verbosity" in build_outcome
     assert "paths to include" in build_outcome
     assert "a required optional argument" in build_outcome
+
+
+@pytest.mark.sphinx(buildername="text", testroot="prog-subcommands")
+def test_prog_subcommands(build_outcome: str) -> None:
+    assert "my-tool" in build_outcome
+    assert "original-name" not in build_outcome
+    assert "my-tool foo" in build_outcome