Handle nested subparsers (#207)

This handles outputting for nested sub-parsers.

First we modify the load_sub_parsers iterator to check if any of the
arguments are subparsers, and if so, recurse into that subparser and
yield its values back too.  (I am as skeptical of yielding from
recursive generator functions as anyone :) If you have hundreds of
levels of nested subparsers I guess this blows up ... but that seems
impractical).

In _mk_sub_command, avoid adding subparsers so they don't show up as
positional arguments (their Action has action.dest of "==SUPPRESS=="
which looks wrong and they don't show up in cmd line help).  The
subparsers are listed in the usage-string, e.g.

  test subparser [-h] [--foo FOO] {child_two} ...

In _build_opt_grp_title we are taking elements[:2] as the title text
for the option group.  This ends up cutting off the full title when
you have nested subparsers.  I have to admit I can't really determine
why this is done, but it does not seem to affect any of the test cases
and the output looks correct to me for nested subparsers, with the
full command listed as the option title.

Author: ianw

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

@@ -0,0 +1,3 @@
+.. sphinx_argparse_cli::
+  :module: parser
+  :func: make

roots/test-subparsers/parser.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser
+
+
+def make() -> ArgumentParser:
+    parser = ArgumentParser(prog="test")
+
+    sub_parsers = parser.add_subparsers()
+    sub_parser = sub_parsers.add_parser("subparser")
+    sub_parser.add_argument("--foo")
+
+    sub_parser_no_child = sub_parsers.add_parser("no_child")
+    sub_parser_no_child.add_argument("argument_one", help="no_child argument")
+
+    sub_sub_parsers = sub_parser.add_subparsers()
+    sub_sub_parser = sub_sub_parsers.add_parser("child_two")
+
+    sub_sub_sub_parsers = sub_sub_parser.add_subparsers()
+    sub_sub_sub_parser = sub_sub_sub_parsers.add_parser("child_three")
+    sub_sub_sub_parser.add_argument("argument", help="sub sub sub child pos argument")
+    sub_sub_sub_parser.add_argument("--flag", help="sub sub sub child argument")
+
+    return parser

src/sphinx_argparse_cli/_logic.py

@@ -132,18 +132,16 @@ def parser(self) -> ArgumentParser:
             self._raw_format = self._parser.formatter_class == RawDescriptionHelpFormatter
         return self._parser
 
-    def load_sub_parsers(self) -> Iterator[tuple[list[str], str, ArgumentParser]]:
-        top_sub_parser = self.parser._subparsers  # noqa: SLF001
-        if not top_sub_parser:
-            return
+    def _load_sub_parsers(
+        self, sub_parser: _SubParsersAction[ArgumentParser]
+    ) -> Iterator[tuple[list[str], str, ArgumentParser]]:
         parser_to_args: dict[int, list[str]] = defaultdict(list)
         str_to_parser: dict[str, ArgumentParser] = {}
-        sub_parser: _SubParsersAction[ArgumentParser]
-        sub_parser = top_sub_parser._group_actions[0]  # type: ignore[assignment]  # noqa: SLF001
         for key, parser in sub_parser._name_parser_map.items():  # noqa: SLF001
             parser_to_args[id(parser)].append(key)
             str_to_parser[key] = parser
         done_parser: set[int] = set()
+
         for name, parser in sub_parser.choices.items():
             parser_id = id(parser)
             if parser_id in done_parser:
@@ -155,6 +153,21 @@ def load_sub_parsers(self) -> Iterator[tuple[list[str], str, ArgumentParser]]:
             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
 
+            # If this parser has a subparser, recurse into it
+            if parser._subparsers:  # noqa: SLF001
+                sub_sub_parser: _SubParsersAction[ArgumentParser]
+                sub_sub_parser = parser._subparsers._group_actions[0]  # type: ignore[assignment]  # noqa: SLF001
+                yield from self._load_sub_parsers(sub_sub_parser)
+
+    def load_sub_parsers(self) -> Iterator[tuple[list[str], str, ArgumentParser]]:
+        top_sub_parser = self.parser._subparsers  # noqa: SLF001
+        if not top_sub_parser:
+            return
+        sub_parser: _SubParsersAction[ArgumentParser]
+        sub_parser = top_sub_parser._group_actions[0]  # type: ignore[assignment]  # noqa: SLF001
+
+        yield from self._load_sub_parsers(sub_parser)
+
     def run(self) -> list[Node]:
         # construct headers
         self.env.note_reread()  # this document needs to be always updated
@@ -202,7 +215,6 @@ def _pre_format(self, block: None | str) -> None | paragraph | literal_block:
     def _mk_option_group(self, group: _ArgumentGroup, prefix: str) -> section:
         sub_title_prefix: str = self.options["group_sub_title_prefix"]
         title_prefix = self.options["group_title_prefix"]
-
         title_text = self._build_opt_grp_title(group, prefix, sub_title_prefix, title_prefix)
         title_ref: str = f"{prefix}{' ' if prefix else ''}{group.title}"
         ref_id = self.make_id(title_ref)
@@ -237,7 +249,7 @@ def _build_opt_grp_title(self, group: _ArgumentGroup, prefix: str, sub_title_pre
                 title_text += f"{elements[0]} "
                 title_text = self._append_title(title_text, sub_title_prefix, elements[0], " ".join(elements[1:]))
             else:
-                title_text += f"{' '.join(elements[:2])} "
+                title_text += f"{' '.join(elements)} "
         else:
             title_text += f"{prefix} "
         title_text += group.title or ""
@@ -347,6 +359,9 @@ def _mk_sub_command(self, aliases: list[str], help_msg: str, parser: ArgumentPar
         for group in parser._action_groups:  # noqa: SLF001
             if not group._group_actions:  # do not show empty groups  # noqa: SLF001
                 continue
+            if isinstance(group._group_actions[0], _SubParsersAction):  # noqa: SLF001
+                # If this is a subparser, ignore it
+                continue
             group_section += self._mk_option_group(group, prefix=parser.prog)
         return group_section
 

tests/test_logic.py

@@ -331,3 +331,18 @@ def test_nested_content(build_outcome: str) -> None:
     assert "<h3>basic-2 opt" in build_outcome
     assert "<p>Some text inside second directive.</p>" in build_outcome
     assert "<p>Some text after directives.</p>" in build_outcome
+
+
+@pytest.mark.sphinx(buildername="html", testroot="subparsers")
+def test_subparsers(build_outcome: str) -> None:
+    assert '<section id="test-options">' in build_outcome
+    assert '<section id="test-subparser">' in build_outcome
+    assert '<section id="test-subparser-options">' in build_outcome
+    assert '<section id="test-subparser-child_two">' in build_outcome
+    assert '<section id="test-subparser-child_two-options">' in build_outcome
+    assert '<section id="test-subparser-child_two-child_three">' in build_outcome
+    assert '<section id="test-subparser-child_two-child_three-positional-arguments">' in build_outcome
+    assert '<section id="test-subparser-child_two-child_three-options">' in build_outcome
+    assert '<section id="test-no_child">' in build_outcome
+    assert '<section id="test-no_child-positional-arguments">' in build_outcome
+    assert '<section id="test-no_child-options">' in build_outcome