🐛 fix: expand {subcommand} to the sub-command name chain (#358)

`{subcommand}` in `:group_sub_title_prefix:` came from `parser.prog`
rather than from the sub-parser name: the section title took the first
word after the program name, and group titles inside the section took
the whole remainder. With a positional argument declared before
`add_subparsers()` the prog is `bar root first`, so `{subcommand}`
became `root`, and for a nested command `tool a list` both `tool a` and
`tool a list` rendered the heading `tool a`; the existing
`test-group-title-prefix-subcommand-replacement` expectation encoded the
`root` case.

The sub-parser walk now carries the chain of command names (`first`,
`first nested`) and passes it to both the section title and the group
titles, so the placeholder expands to the command path in every heading.
Anchors do not change since they still derive from `parser.prog`. 🧭

The updated expectation in
`test_group_title_prefix_sub_command_replacement` reads `bar
baronlyfirst (f)` instead of `bar baronlyroot (f)`.

Author: gaborbernat

CHANGELOG.md

@@ -26,6 +26,8 @@ All notable changes to this project will be documented in this file.
   in the usage line; user-supplied metavars keep their case instead of being upper-cased.
 - Expand argparse format specifiers such as `%(prog)s`, `%(default)s` and `%(choices)s` in help, descriptions and
   epilogs, and skip the generated `(default: ...)` when the help already mentions a default in any case.
+- 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

@@ -126,8 +126,8 @@ def _make_id(self) -> Callable[[str], str]:
         return make_id_lower if "force_refs_lower" in self.options else make_id
 
     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)
@@ -144,12 +144,13 @@ def _load_sub_parsers(
             help_msg = next((a.help for a in sub_parser._choices_actions if a.dest == name), None)  # noqa: SLF001
             if help_msg == SUPPRESS:
                 continue
-            yield aliases, help_msg or "", parser
+            sub_cmd = f"{parent_cmd} {name}".strip()
+            yield aliases, help_msg or "", parser, sub_cmd
 
             if (sub_sub_parser := _sub_parser_action(parser)) is not None:
-                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]]:
         if (sub_parser := _sub_parser_action(self.parser)) is not None:
             yield from self._load_sub_parsers(sub_parser)
 
@@ -177,10 +178,9 @@ def run(self) -> list[Node]:
                     actions,
                     self.parser,
                     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), self.parser):
             home_section += epilog
@@ -204,13 +204,19 @@ def _pre_format(self, block: str | None, parser: ArgumentParser) -> paragraph |
         return para
 
     def _mk_option_group(
-        self, group: _ArgumentGroup, actions: list[Action], parser: ArgumentParser, prefix: str, prog: str
+        self,
+        group: _ArgumentGroup,
+        actions: list[Action],
+        parser: ArgumentParser,
+        prefix: str,
+        sub_cmd: str | None = None,
     ) -> section:
+        prog = self.parser.prog.split("/")[-1]
         sub_title_prefix: str = self.options.get("group_sub_title_prefix")
         title_prefix = self.options.get("group_title_prefix")
         # an untitled group borrows its description as heading so its anchor stays unique
         group_title = group.title or group.description or "arguments"
-        title_text = self._build_opt_grp_title(group_title, prefix, prog, sub_title_prefix, title_prefix)
+        title_text = self._resolve_prefix(prog, sub_cmd, prefix, title_prefix, sub_title_prefix) + group_title
         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
@@ -225,12 +231,6 @@ def _mk_option_group(
         group_section += opt_group
         return group_section
 
-    def _build_opt_grp_title(
-        self, group_title: str, 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
-        return self._resolve_prefix(prog, sub_cmd, prefix, title_prefix, sub_title_prefix) + group_title
-
     def _mk_option_line(self, parser: ArgumentParser, action: Action, prefix: str) -> list_item:
         line = paragraph()
         if action.option_strings:
@@ -308,15 +308,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)})"
@@ -338,18 +339,11 @@ def _mk_sub_command(self, aliases: list[str], help_msg: str, parser: ArgumentPar
 
         for group in parser._action_groups:  # noqa: SLF001
             if actions := _visible_actions(group):
-                group_section += self._mk_option_group(
-                    group, actions, parser, prefix=parser.prog, prog=self.parser.prog.split("/")[-1]
-                )
+                group_section += self._mk_option_group(group, actions, parser, prefix=parser.prog, sub_cmd=sub_cmd)
         if epilog := self._pre_format(parser.epilog, parser):
             group_section += epilog
         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

@@ -420,6 +420,18 @@ def test_usage_ignores_python_colors(build_outcome: str) -> None:
     )
 
 
+@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="help-nodes")
 def test_help_nodes_as_text(build_outcome: str) -> None:
     assert (
@@ -538,8 +550,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")