🐛 fix: derive {subcommand} from sub-parser names

The placeholder took its value from parser.prog: the first word after
the program name for section titles and the whole remainder for group
titles. A positional declared before add_subparsers() made it the
positional's name, and nested commands collapsed onto their parent's
heading.

Carry the chain of sub-parser names through the walk and use it for
both title kinds. Anchors still derive from parser.prog.

Author: gaborbernat

CHANGELOG.md

@@ -9,6 +9,8 @@ All notable changes to this project will be documented in this file.
 - Add `force_refs_lower` to enable `:ref:` links with mixed-case program names and arguments.
 - Fix Sphinx smart quotes rewriting `--` to an en dash in `--option` names within descriptions, epilogs, and help text.
 - Register flags and positional arguments as Sphinx program options so the `:option:` role links to them.
+- Make `{subcommand}` in `:group_sub_title_prefix:` expand to the sub-command names (`first nested`) instead of the
+  first word after the program name, which was a positional argument or only the outermost command.
 
 ## 1.13.1
 

roots/test-subcommand-placeholder/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-subcommand-placeholder/index.rst

@@ -0,0 +1,4 @@
+.. sphinx_argparse_cli::
+  :module: parser
+  :func: make
+  :group_sub_title_prefix: {subcommand}

roots/test-subcommand-placeholder/parser.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser
+
+
+def make() -> ArgumentParser:
+    parser = ArgumentParser(prog="prog", add_help=False)
+    parser.add_argument("root", help="root positional")
+    first = parser.add_subparsers(title="commands").add_parser("first", aliases=["f"], add_help=False)
+    first.add_argument("--flag", help="first flag")
+    first.add_subparsers(title="commands").add_parser("nested", add_help=False).add_argument("--deep", help="deep flag")
+    return parser

src/sphinx_argparse_cli/_logic.py

@@ -130,8 +130,8 @@ def _raw_format(self) -> bool:
         return isinstance(formatter, type) and issubclass(formatter, RawDescriptionHelpFormatter)
 
     def _load_sub_parsers(
-        self, sub_parser: _SubParsersAction[ArgumentParser]
-    ) -> Iterator[tuple[list[str], str, ArgumentParser]]:
+        self, sub_parser: _SubParsersAction[ArgumentParser], parent_cmd: str = ""
+    ) -> Iterator[tuple[list[str], str, ArgumentParser, str]]:
         parser_to_args: dict[int, list[str]] = defaultdict(list)
         for key, parser in sub_parser._name_parser_map.items():  # noqa: SLF001
             parser_to_args[id(parser)].append(key)
@@ -146,14 +146,15 @@ def _load_sub_parsers(
             aliases.remove(name)
             # help is stored in a pseudo action
             help_msg = next((a.help for a in sub_parser._choices_actions if a.dest == name), None) or ""  # noqa: SLF001
-            yield aliases, help_msg, parser
+            sub_cmd = f"{parent_cmd} {name}".strip()
+            yield aliases, help_msg, parser, sub_cmd
 
             if parser._subparsers:  # noqa: SLF001
                 sub_sub_parser: _SubParsersAction[ArgumentParser] = parser._subparsers._group_actions[0]  # type: ignore[assignment]  # noqa: SLF001
                 if isinstance(sub_sub_parser, _SubParsersAction):
-                    yield from self._load_sub_parsers(sub_sub_parser)
+                    yield from self._load_sub_parsers(sub_sub_parser, sub_cmd)
 
-    def _iter_sub_commands(self) -> Iterator[tuple[list[str], str, ArgumentParser]]:
+    def _iter_sub_commands(self) -> Iterator[tuple[list[str], str, ArgumentParser, str]]:
         top_sub_parser = self.parser._subparsers  # noqa: SLF001
         if not top_sub_parser:
             return
@@ -183,8 +184,8 @@ def run(self) -> list[Node]:
             home_section += self._mk_option_group(
                 group, prefix=self.parser.prog.split("/")[-1], prog=self.parser.prog.split("/")[-1]
             )
-        for aliases, help_msg, parser in self._iter_sub_commands():
-            home_section += self._mk_sub_command(aliases, help_msg, parser)
+        for aliases, help_msg, parser, sub_cmd in self._iter_sub_commands():
+            home_section += self._mk_sub_command(aliases, help_msg, parser, sub_cmd)
 
         if epilog := self._pre_format(self.options.get("epilog", self.parser.epilog)):
             home_section += epilog
@@ -205,10 +206,10 @@ def _pre_format(self, block: str | None) -> paragraph | literal_block | None:
         _protect_option_dashes(para)
         return para
 
-    def _mk_option_group(self, group: _ArgumentGroup, prefix: str, prog: str) -> section:
+    def _mk_option_group(self, group: _ArgumentGroup, prefix: str, prog: str, sub_cmd: str | None = None) -> section:
         sub_title_prefix: str = self.options.get("group_sub_title_prefix")
         title_prefix = self.options.get("group_title_prefix")
-        title_text = self._build_opt_grp_title(group, prefix, prog, sub_title_prefix, title_prefix)
+        title_text = self._resolve_prefix(prog, sub_cmd, prefix, title_prefix, sub_title_prefix) + (group.title or "")
         title_ref: str = f"{prefix}{' ' if prefix else ''}{group.title}"
         ref_id = self._make_id(title_ref)
         # the text sadly needs to be prefixed, because otherwise the autosectionlabel will conflict
@@ -226,14 +227,6 @@ def _mk_option_group(self, group: _ArgumentGroup, prefix: str, prog: str) -> sec
         group_section += opt_group
         return group_section
 
-    def _build_opt_grp_title(
-        self, group: _ArgumentGroup, prefix: str, prog: str, sub_title_prefix: str, title_prefix: str
-    ) -> str:
-        sub_cmd = prefix[len(prog) :].strip() or None if prefix != prog else None
-        title_text = self._resolve_prefix(prog, sub_cmd, prefix, title_prefix, sub_title_prefix)
-        title_text += group.title or ""
-        return title_text
-
     def _mk_option_line(self, action: Action, prefix: str) -> list_item:
         line = paragraph()
         as_key = action.dest
@@ -310,15 +303,16 @@ def _register_ref(
         self._std_domain.anonlabels[name] = doc_name, ref_name
         self._std_domain.labels[name] = doc_name, ref_name, ref_title
 
-    def _mk_sub_command(self, aliases: list[str], help_msg: str, parser: ArgumentParser) -> section:
+    def _mk_sub_command(self, aliases: list[str], help_msg: str, parser: ArgumentParser, sub_cmd: str) -> section:
         sub_title_prefix: str = self.options.get("group_sub_title_prefix")
         title_prefix: str = self.options.get("group_title_prefix")
 
         if sys.version_info >= (3, 14):  # pragma: >=3.14 cover
             # https://github.com/python/cpython/issues/139809
             parser.prog = _strip_ansi_colors(parser.prog)
 
-        title_text = self._build_sub_cmd_title(parser, sub_title_prefix, title_prefix)
+        root_prog = self.parser.prog.split("/")[-1]
+        title_text = self._resolve_prefix(root_prog, sub_cmd, parser.prog, title_prefix, sub_title_prefix).rstrip()
         title_ref: str = parser.prog
         if aliases:
             aliases_text: str = f" ({', '.join(aliases)})"
@@ -346,14 +340,9 @@ def _mk_sub_command(self, aliases: list[str], help_msg: str, parser: ArgumentPar
                 continue
             if isinstance(group._group_actions[0], _SubParsersAction):  # noqa: SLF001
                 continue
-            group_section += self._mk_option_group(group, prefix=parser.prog, prog=self.parser.prog.split("/")[-1])
+            group_section += self._mk_option_group(group, prefix=parser.prog, prog=root_prog, sub_cmd=sub_cmd)
         return group_section
 
-    def _build_sub_cmd_title(self, parser: ArgumentParser, sub_title_prefix: str, title_prefix: str) -> str:
-        root_prog = self.parser.prog.split("/")[-1]
-        sub_cmd = parser.prog[len(root_prog) :].strip().split(" ", maxsplit=1)[0]
-        return self._resolve_prefix(root_prog, sub_cmd, parser.prog, title_prefix, sub_title_prefix).rstrip()
-
     def _resolve_prefix(
         self,
         prog_name: str,

tests/test_logic.py

@@ -228,6 +228,16 @@ def test_option_role_as_html(build_outcome: str, warning: StringIO) -> None:
         "#prog-run---magic",
     ]
     assert not warning.getvalue()
+@pytest.mark.sphinx(buildername="html", testroot="subcommand-placeholder")
+def test_sub_command_placeholder_nested(build_outcome: str) -> None:
+    headings = re.findall(r'<h[23]>([^<]*)<a class="headerlink" href="(#[^"]*)"', build_outcome)
+    assert headings == [
+        ("prog positional arguments", "#prog-positional-arguments"),
+        ("prog first (f)", "#prog-root-first-(f)"),
+        ("prog first options", "#prog-root-first-options"),
+        ("prog first nested", "#prog-root-first-nested"),
+        ("prog first nested options", "#prog-root-first-nested-options"),
+    ]
 
 
 @pytest.mark.sphinx(buildername="text", testroot="ref-duplicate-label")
@@ -301,8 +311,8 @@ def test_group_title_prefix_sub_command_replacement(build_outcome: str, opt_grp_
     grp, anchor = opt_grp_name
     assert f'<h2>bar {grp}<a class="headerlink" href="#bar-{anchor}"' in build_outcome
     assert '<h2>bar Exclusive<a class="headerlink" href="#bar-Exclusive"' in build_outcome
-    assert '<h2>bar baronlyroot (f)<a class="headerlink" href="#bar-root-first-(f)"' in build_outcome
-    assert '<h3>bar baronlyroot first positional arguments<a class="headerlink"' in build_outcome
+    assert '<h2>bar baronlyfirst (f)<a class="headerlink" href="#bar-root-first-(f)"' in build_outcome
+    assert '<h3>bar baronlyfirst positional arguments<a class="headerlink"' in build_outcome
 
 
 @pytest.mark.sphinx(buildername="html", testroot="store-true-false")