🐛 fix: skip sub-commands whose help is SUPPRESS (#357)

A sub-command registered with `add_parser("secret", help=SUPPRESS)` is
hidden from argparse's own `--help`, yet the directive rendered a `prog
secret` section whose description read `==SUPPRESS==`, because the code
took the pseudo action's help text verbatim.

The sub-parser walk now skips sub-commands whose help is `SUPPRESS`,
matching how suppressed arguments are already left out of option groups.
The usage line still lists them in `{run,secret}`, because argparse
prints that itself. 🙈

Author: gaborbernat

CHANGELOG.md

@@ -13,6 +13,7 @@ All notable changes to this project will be documented in this file.
   literals.
 - Make `:hook:` intercept `parse_intermixed_args()` as well as `parse_args()`.
 - Keep ANSI color codes out of usage blocks when `PYTHON_COLORS=1` is set on Python 3.14 or newer.
+- Skip sub-commands added with `help=argparse.SUPPRESS` instead of rendering them with a `==SUPPRESS==` description.
 
 ## 1.13.1
 

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

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

roots/test-subparsers-suppressed/parser.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from argparse import SUPPRESS, ArgumentParser
+
+
+def make() -> ArgumentParser:
+    parser = ArgumentParser(prog="prog", add_help=False)
+    sub = parser.add_subparsers()
+    sub.add_parser("run", help="run it", add_help=False)
+    sub.add_parser("secret", help=SUPPRESS, add_help=False)
+    return parser

src/sphinx_argparse_cli/_logic.py

@@ -146,8 +146,10 @@ def _load_sub_parsers(
             aliases = parser_to_args[id(parser)]
             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
+            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
 
             if parser._subparsers:  # noqa: SLF001
                 sub_sub_parser: _SubParsersAction[ArgumentParser] = parser._subparsers._group_actions[0]  # type: ignore[assignment]  # noqa: SLF001

tests/test_logic.py

@@ -273,6 +273,26 @@ def test_option_role_as_html(build_outcome: str, warning: StringIO) -> None:
     assert not warning.getvalue()
 
 
+@pytest.mark.sphinx(buildername="text", testroot="subparsers-suppressed")
+def test_suppressed_sub_command(build_outcome: str) -> None:
+    assert (
+        build_outcome
+        == """prog - CLI interface
+********************
+
+   prog {run,secret} ...
+
+
+prog run
+========
+
+run it
+
+   prog run
+"""
+    )
+
+
 @pytest.mark.sphinx(buildername="text", testroot="python-colors")
 def test_usage_ignores_python_colors(build_outcome: str) -> None:
     assert (