sphinx-argparse-cli 1.22.0__tar.gz → 1.23.0__tar.gz

{sphinx_argparse_cli-1.22.0 → sphinx_argparse_cli-1.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: sphinx-argparse-cli
-Version: 1.22.0
+Version: 1.23.0
 Summary: render CLI arguments (sub-commands friendly) defined by argparse module
 Project-URL: Documentation, https://github.com/tox-dev/sphinx-argparse-cli#sphinx-argparse-cli
 Project-URL: Homepage, https://github.com/tox-dev/sphinx-argparse-cli
@@ -164,6 +164,23 @@ With `sphinx_argparse_cli_prefix_document = True` (anchors prefixed by document
 
 The anchor text is visible after the `#` in the URL when you click a heading.
 
+Flags and positional arguments are also registered as Sphinx program options, so the `:option:` role works with the
+program (and sub-command) name followed by the argument, or scoped through a `.. program::` directive:
+
+```rst
+:option:`tox --magic`
+:option:`tox run --magic`
+
+.. program:: tox run
+
+:option:`--magic`
+:option:`--magic=value`
+```
+
+`:option:` targets keep their original case, so they do not need `:force_refs_lower:`. They ignore
+`sphinx_argparse_cli_prefix_document`; when two documents render the same program, the role links to the first one
+Sphinx reads.
+
 ### Handle mixed-case references
 
 Sphinx `:ref:` only supports lower-case targets. When your program name or flags contain capital letters, set
@@ -187,6 +204,14 @@ For a program named `SampleProgram`:
 If you do not need Sphinx `:ref:` cross-references you can leave this off to keep mixed-case anchors in the HTML output,
 but enabling it later will change existing anchor URLs.
 
+### Write help text as reStructuredText
+
+The directive parses every argument's `help` string as reStructuredText, so inline markup such as a `:ref:` role or
+`**bold**` works. The same applies to characters that carry meaning in reStructuredText: a lone `*` (`match *.py`), a
+trailing `_` (`name_`), backticks, or a trailing `::` produce docutils warnings and fail a build run with `-W`. Escape
+them with a backslash (`match \*.py`) or wrap them in inline literals. Text between matching single quotes, double
+quotes, or braces becomes an inline literal for you, so `pick 'fast' or "slow"` shows `'fast'` and `"slow"` as code.
+
 ### Add extra content after generated docs
 
 Any content nested inside the directive is appended after the generated CLI documentation:

{sphinx_argparse_cli-1.22.0 → sphinx_argparse_cli-1.23.0}/README.md

@@ -132,6 +132,23 @@ With `sphinx_argparse_cli_prefix_document = True` (anchors prefixed by document
 
 The anchor text is visible after the `#` in the URL when you click a heading.
 
+Flags and positional arguments are also registered as Sphinx program options, so the `:option:` role works with the
+program (and sub-command) name followed by the argument, or scoped through a `.. program::` directive:
+
+```rst
+:option:`tox --magic`
+:option:`tox run --magic`
+
+.. program:: tox run
+
+:option:`--magic`
+:option:`--magic=value`
+```
+
+`:option:` targets keep their original case, so they do not need `:force_refs_lower:`. They ignore
+`sphinx_argparse_cli_prefix_document`; when two documents render the same program, the role links to the first one
+Sphinx reads.
+
 ### Handle mixed-case references
 
 Sphinx `:ref:` only supports lower-case targets. When your program name or flags contain capital letters, set
@@ -155,6 +172,14 @@ For a program named `SampleProgram`:
 If you do not need Sphinx `:ref:` cross-references you can leave this off to keep mixed-case anchors in the HTML output,
 but enabling it later will change existing anchor URLs.
 
+### Write help text as reStructuredText
+
+The directive parses every argument's `help` string as reStructuredText, so inline markup such as a `:ref:` role or
+`**bold**` works. The same applies to characters that carry meaning in reStructuredText: a lone `*` (`match *.py`), a
+trailing `_` (`name_`), backticks, or a trailing `::` produce docutils warnings and fail a build run with `-W`. Escape
+them with a backslash (`match \*.py`) or wrap them in inline literals. Text between matching single quotes, double
+quotes, or braces becomes an inline literal for you, so `pick 'fast' or "slow"` shows `'fast'` and `"slow"` as code.
+
 ### Add extra content after generated docs
 
 Any content nested inside the directive is appended after the generated CLI documentation:

{sphinx_argparse_cli-1.22.0 → sphinx_argparse_cli-1.23.0}/src/sphinx_argparse_cli/_logic.py

@@ -16,6 +16,7 @@ from argparse import (
 )
 from collections import defaultdict
 from contextlib import contextmanager
+from functools import cached_property
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, ClassVar, Final, cast
 from unittest.mock import patch
@@ -42,13 +43,13 @@ from docutils.nodes import (
 from docutils.parsers.rst.directives import flag, positive_int, unchanged, unchanged_required
 from docutils.statemachine import StringList
 from sphinx.locale import __
+from sphinx.util import ws_re
 from sphinx.util.docutils import SphinxDirective
 from sphinx.util.logging import getLogger
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Callable, Iterator, Sequence
 
-    from docutils.parsers.rst.states import RSTState, RSTStateMachine
     from sphinx.domains.std import StandardDomain
     from sphinx.util.logging import SphinxLoggerAdapter
 
@@ -77,70 +78,56 @@ class SphinxArgparseCli(SphinxDirective):
         "force_refs_lower": flag,
     }
 
-    def __init__(  # noqa: PLR0913
-        self,
-        name: str,
-        arguments: list[str],
-        options: dict[str, str | None],
-        content: StringList,
-        lineno: int,
-        content_offset: int,
-        block_text: str,
-        state: RSTState,
-        state_machine: RSTStateMachine,
-    ) -> None:
-        options.setdefault("group_title_prefix", None)
-        options.setdefault("group_sub_title_prefix", None)
-        super().__init__(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)
-        self._parser: ArgumentParser | None = None
-        self._std_domain: StandardDomain = cast("StandardDomain", self.env.get_domain("std"))
-        self._raw_format: bool = False
-        self._make_id = make_id_lower if "force_refs_lower" in self.options else make_id
-
-    @property
+    @cached_property
     def parser(self) -> ArgumentParser:
-        if self._parser is None:
-            module_name, attr_name = self.options["module"], self.options["func"]
-            try:
-                module = __import__(module_name, fromlist=[attr_name])
-            except ImportError:
-                msg = f"Failed to import module {module_name!r}"
-                raise self.error(msg)  # noqa: B904
-            try:
-                parser_creator = getattr(module, attr_name)
-            except AttributeError:
-                del sys.modules[module_name]
-                msg = f"Module {module_name!r} has no attribute {attr_name!r}"
-                raise self.error(msg)  # noqa: B904
-            if "hook" in self.options:
-                original_parse_known_args = ArgumentParser.parse_known_args
-                ArgumentParser.parse_known_args = _parse_known_args_hook  # type: ignore[method-assign,assignment]
+        module_name, attr_name = self.options["module"], self.options["func"]
+        try:
+            module = __import__(module_name, fromlist=[attr_name])
+        except ImportError:
+            msg = f"Failed to import module {module_name!r}"
+            raise self.error(msg)  # noqa: B904
+        try:
+            parser_creator = getattr(module, attr_name)
+        except AttributeError:
+            del sys.modules[module_name]
+            msg = f"Module {module_name!r} has no attribute {attr_name!r}"
+            raise self.error(msg)  # noqa: B904
+        parser: ArgumentParser | None = None
+        if "hook" in self.options:
+            # parse_intermixed_args bypasses parse_known_args since Python 3.12, so both entry points need the hook
+            with (
+                patch.object(ArgumentParser, "parse_known_args", _parse_known_args_hook),
+                patch.object(ArgumentParser, "parse_known_intermixed_args", _parse_known_args_hook),
+            ):
                 try:
                     parser_creator()
                 except HookError as hooked:
-                    self._parser = hooked.parser
-                finally:
-                    ArgumentParser.parse_known_args = original_parse_known_args
-            else:
-                self._parser = parser_creator()
+                    parser = hooked.parser
+        else:
+            parser = parser_creator()
 
-            del sys.modules[module_name]
-            if self._parser is None:
-                msg = "Failed to hook argparse to get ArgumentParser"
-                raise self.error(msg)
+        del sys.modules[module_name]
+        if parser is None:
+            msg = "Failed to hook argparse to get ArgumentParser"
+            raise self.error(msg)
+
+        if "prog" in self.options:
+            old_prog, new_prog = parser.prog, self.options["prog"]
+            parser.prog = new_prog
+            _update_sub_parser_prog(parser, old_prog, new_prog)
+        return parser
 
-            if "prog" in self.options:
-                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)
+    @cached_property
+    def _std_domain(self) -> StandardDomain:
+        return cast("StandardDomain", self.env.get_domain("std"))
 
-            formatter = self._parser.formatter_class
-            self._raw_format = isinstance(formatter, type) and issubclass(formatter, RawDescriptionHelpFormatter)
-        return self._parser
+    @cached_property
+    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)
@@ -154,19 +141,18 @@ class SphinxArgparseCli(SphinxDirective):
             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
+            sub_cmd = f"{parent_cmd} {name}".strip()
+            yield aliases, help_msg or "", parser, sub_cmd
 
-            if parser._subparsers:  # noqa: SLF001
-                sub_sub_parser: _SubParsersAction[ArgumentParser] = parser._subparsers._group_actions[0]  # type: ignore[assignment]  # noqa: SLF001
-                yield from self._load_sub_parsers(sub_sub_parser)
+            if (sub_sub_parser := _sub_parser_action(parser)) is not None:
+                yield from self._load_sub_parsers(sub_sub_parser, sub_cmd)
 
-    def _iter_sub_commands(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] = top_sub_parser._group_actions[0]  # type: ignore[assignment]  # noqa: SLF001
-        yield from self._load_sub_parsers(sub_parser)
+    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)
 
     def run(self) -> list[Node]:
         self.env.note_reread()  # this document needs to always be rebuilt
@@ -179,22 +165,24 @@ class SphinxArgparseCli(SphinxDirective):
         if "usage_first" in self.options:
             home_section += self._mk_usage(self.parser)
 
-        if description := self._pre_format(self.options.get("description", self.parser.description)):
+        if description := self._pre_format(self.options.get("description", self.parser.description), self.parser):
             home_section += description
 
         if "usage_first" not in self.options:
             home_section += self._mk_usage(self.parser)
 
         for group in self.parser._action_groups:  # noqa: SLF001
-            if not group._group_actions or group is self.parser._subparsers:  # noqa: SLF001
-                continue
-            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)
-
-        if epilog := self._pre_format(self.options.get("epilog", self.parser.epilog)):
+            if actions := _visible_actions(group):
+                home_section += self._mk_option_group(
+                    group,
+                    actions,
+                    self.parser,
+                    prefix=self.parser.prog.split("/")[-1],
+                )
+        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
 
         if self.content:
@@ -202,10 +190,12 @@ class SphinxArgparseCli(SphinxDirective):
 
         return [home_section]
 
-    def _pre_format(self, block: None | str) -> None | paragraph | literal_block:
-        if block is None:
+    def _pre_format(self, block: str | None, parser: ArgumentParser) -> paragraph | literal_block | None:
+        if block is None or not block.strip():
             return None
-        if self._raw_format and "\n" in block:
+        block = _expand_prog(block, parser.prog)
+        formatter = parser.formatter_class
+        if "\n" in block and isinstance(formatter, type) and issubclass(formatter, RawDescriptionHelpFormatter):
             lit = literal_block("", Text(block), classes=["sphinx-argparse-cli-wrap"])
             lit["language"] = "none"
             return lit
@@ -213,75 +203,75 @@ class SphinxArgparseCli(SphinxDirective):
         _protect_option_dashes(para)
         return para
 
-    def _mk_option_group(self, group: _ArgumentGroup, prefix: str, prog: 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, prog, sub_title_prefix, title_prefix)
-        title_ref: str = f"{prefix}{' ' if prefix else ''}{group.title}"
+    def _mk_option_group(
+        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._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
         header = title("", Text(title_text))
         group_section = section("", header, ids=[ref_id], names=[ref_id])
-        if description := self._pre_format(group.description):
+        if group.title and (description := self._pre_format(group.description, parser)):
             group_section += description
         self._register_ref(ref_id, title_text, group_section)
         opt_group = bullet_list()
-        for action in group._group_actions:  # noqa: SLF001
-            if action.help == SUPPRESS:
-                continue
-            point = self._mk_option_line(action, prefix)
-            opt_group += point
+        for action in actions:
+            opt_group += self._mk_option_line(parser, action, prefix)
         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:
+    def _mk_option_line(self, parser: ArgumentParser, action: Action, prefix: str) -> list_item:
         line = paragraph()
-        as_key = action.dest
-        if action.metavar:
-            as_key = action.metavar if isinstance(action.metavar, str) else action.metavar[0]
         if action.option_strings:
+            args_text = _format_args(parser, action) if action.nargs != 0 else None
             for at, opt in enumerate(action.option_strings):
                 if at:
                     line += Text(", ")
                 self._mk_option_name(line, prefix, opt)
-                if action.nargs != 0:
+                if args_text is not None:
                     line += Text(" ")
-                    metavar_text = (
-                        " ".join(meta.upper() for meta in action.metavar)
-                        if isinstance(action.metavar, tuple)
-                        else as_key.upper()
-                    )
-                    line += literal(text=metavar_text)
+                    line += literal(text=args_text)
         else:
-            self._mk_option_name(line, prefix, as_key)
+            metavar = action.metavar
+            self._mk_option_name(
+                line, prefix, " ".join(metavar) if isinstance(metavar, tuple) else metavar or action.dest
+            )
 
-        if action.help:
-            help_text = load_help_text(action.help)
+        extra: Sequence[Node] = ()
+        if help_text := _expand_help(action, parser.prog):
             temp = paragraph()
-            self.state.nested_parse(StringList(help_text.split("\n")), 0, temp)
-            line += Text(" - ")
-            for content in cast("paragraph", temp.children[0]).children:
-                line += content
+            self.state.nested_parse(StringList(load_help_text(help_text).split("\n")), 0, temp)
+            # only a leading paragraph can share the option's line; anything else becomes a block under it
+            if temp.children and isinstance(temp.children[0], paragraph):
+                line += Text(" - ")
+                line += temp.children[0].children
+                extra = temp.children[1:]
+            else:
+                extra = temp.children
         if (
             "no_default_values" not in self.options
             and action.default is not None
             and action.default != SUPPRESS
-            and not re.match(r".*[ (]default[s]? .*", (action.help or ""))
+            and not _DEFAULT_IN_HELP.search(help_text)
             and not isinstance(action, _StoreTrueAction | _StoreFalseAction)
         ):
             line += Text(" (default: ")
             line += literal(text=str(action.default).replace(str(Path.cwd()), "{cwd}"))
             line += Text(")")
-        _protect_option_dashes(line)
-        return list_item("", line, ids=[])
+        item = list_item("", line, *extra, ids=[])
+        _protect_option_dashes(item)
+        return item
 
     def _mk_option_name(self, line: paragraph, prefix: str, opt: str) -> None:
         ref_id = self._make_id(f"{prefix}-{opt}")
@@ -290,6 +280,7 @@ class SphinxArgparseCli(SphinxDirective):
         line.attributes["ids"].append(ref_id)
         ref += strong("", "", literal(text=opt))
         self._register_ref(ref_id, ref_title, ref, is_cli_option=True)
+        self._std_domain.add_program_option(ws_re.sub("-", prefix), opt, self.env.docname, ref_id)
         line += ref
 
     def _register_ref(
@@ -317,15 +308,16 @@ class SphinxArgparseCli(SphinxDirective):
         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:
-        sub_title_prefix: str = self.options["group_sub_title_prefix"]
-        title_prefix: str = self.options["group_title_prefix"]
+    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)})"
@@ -339,28 +331,19 @@ class SphinxArgparseCli(SphinxDirective):
         if "usage_first" in self.options:
             group_section += self._mk_usage(parser)
 
-        command_desc = (parser.description or help_msg or "").strip()
-        if command_desc:
-            desc_paragraph = paragraph("", Text(command_desc))
-            _protect_option_dashes(desc_paragraph)
-            group_section += desc_paragraph
+        if command_desc := (parser.description or help_msg).strip():
+            group_section += self._pre_format(command_desc, parser)
 
         if "usage_first" not in self.options:
             group_section += self._mk_usage(parser)
 
         for group in parser._action_groups:  # noqa: SLF001
-            if not group._group_actions:  # noqa: SLF001
-                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])
+            if actions := _visible_actions(group):
+                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,
@@ -397,18 +380,25 @@ class SphinxArgparseCli(SphinxDirective):
         return title_text
 
     def _mk_usage(self, parser: ArgumentParser) -> literal_block:
-        parser.formatter_class = lambda prog: HelpFormatter(prog, width=self.options.get("usage_width", 100))
-        with self._no_color():
+        width = self.options.get("usage_width", 100)
+        with patch.object(parser, "formatter_class", lambda prog: HelpFormatter(prog, width=width)), self._no_color():
             texts = parser.format_usage()[len("usage: ") :].splitlines()
         texts = [line if at == 0 else f"{' ' * (len(parser.prog) + 1)}{line.lstrip()}" for at, line in enumerate(texts)]
         return literal_block("", Text("\n".join(texts)), classes=["sphinx-argparse-cli-wrap"])
 
     @contextmanager
     def _no_color(self) -> Iterator[None]:
-        with patch.dict(os.environ, {"NO_COLOR": "1"}, clear=False):
+        # PYTHON_COLORS=1 outranks NO_COLOR in argparse, so both must be set to get plain text
+        with patch.dict(os.environ, {"NO_COLOR": "1", "PYTHON_COLORS": "0"}, clear=False):
             yield
 
 
+def _format_args(parser: ArgumentParser, action: Action) -> str:
+    # argparse's formatter keeps the text in step with the usage line: nargs, choices and user metavars included
+    formatter = parser._get_formatter()  # noqa: SLF001
+    return formatter._format_args(action, formatter._get_default_metavar_for_optional(action))  # noqa: SLF001
+
+
 def make_id_lower(key: str) -> str:
     return re.sub("[A-Z]", lambda m: f"_{m.group(0).lower()}", make_id(key))
 
@@ -417,9 +407,46 @@ def make_id(key: str) -> str:
     return "-".join(key.split()).rstrip("-")
 
 
+def _sub_parser_action(parser: ArgumentParser) -> _SubParsersAction[ArgumentParser] | None:
+    # add_subparsers reuses the positional group, so the action may sit after positional arguments;
+    # isinstance cannot recover the type parameter, hence the cast
+    found = next((action for action in parser._actions if isinstance(action, _SubParsersAction)), None)  # noqa: SLF001
+    return cast("_SubParsersAction[ArgumentParser] | None", found)
+
+
+def _visible_actions(group: _ArgumentGroup) -> list[Action]:
+    # sub-commands get their own sections, and a heading over an empty list helps nobody
+    return [
+        action
+        for action in group._group_actions  # noqa: SLF001
+        if action.help != SUPPRESS and not isinstance(action, _SubParsersAction)
+    ]
+
+
+def _expand_prog(text: str, prog: str) -> str:
+    # what argparse.HelpFormatter._format_text does for descriptions and epilogs
+    return text % {"prog": prog} if "%(prog)" in text else text
+
+
+def _expand_help(action: Action, prog: str) -> str:
+    # mirrors argparse.HelpFormatter._expand_help so the help reads as it does under --help
+    help_text = action.help or ""
+    if "%" not in help_text:
+        return help_text
+    params = {
+        key: getattr(value, "__name__", value) for key, value in vars(action).items() if value is not SUPPRESS
+    } | {"prog": prog}
+    if action.choices is not None:
+        params["choices"] = ", ".join(map(str, action.choices))
+    return help_text % params
+
+
+_DEFAULT_IN_HELP: Final[re.Pattern[str]] = re.compile(r"\bdefaults?\b", re.IGNORECASE)
+
 _HELP_SUBSTITUTIONS: Final[list[tuple[re.Pattern[str], str]]] = [
-    (re.compile(r"[']+(.+?)[']+"), "``'\\1'``"),
-    (re.compile(r'["]+(.+?)["]+'), '``"\\1"``'),
+    # a quote glued to a word character is an apostrophe (don't, it's), not the edge of a quoted span
+    (re.compile(r"(?<!\w)'([^']+?)'(?!\w)"), "``'\\1'``"),
+    (re.compile(r'(?<!\w)"([^"]+?)"(?!\w)'), '``"\\1"``'),
     (re.compile(r"[{](.+?)[}]"), "``{\\1}``"),
 ]
 
@@ -470,9 +497,8 @@ def _strip_ansi_colors(text: str) -> str:  # pragma: >=3.14 cover
 
 
 def _update_sub_parser_prog(parser: ArgumentParser, old_prog: str, new_prog: str) -> None:
-    if not (sub_parsers := parser._subparsers):  # noqa: SLF001
+    if (sub_action := _sub_parser_action(parser)) is None:
         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)

{sphinx_argparse_cli-1.22.0 → sphinx_argparse_cli-1.23.0}/src/sphinx_argparse_cli/version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.22.0'
-__version_tuple__ = version_tuple = (1, 22, 0)
+__version__ = version = '1.23.0'
+__version_tuple__ = version_tuple = (1, 23, 0)
 
 __commit_id__ = commit_id = None

{sphinx_argparse_cli-1.22.0 → sphinx_argparse_cli-1.23.0}/tests/complex.txt

@@ -16,7 +16,7 @@ complex options
 
 * **"--no-help"**
 
-* **"--outdir"** "OUT_DIR", **"-o"** "OUT_DIR" - output directory
+* **"--outdir"** "out_dir", **"-o"** "out_dir" - output directory
 
 * **"--in-dir"** "IN_DIR", **"-i"** "IN_DIR" - input directory
 

{sphinx_argparse_cli-1.22.0 → sphinx_argparse_cli-1.23.0}/tests/complex_pre_310.txt

@@ -16,7 +16,7 @@ complex optional arguments
 
 * **"--no-help"**
 
-* **"--outdir"** "OUT_DIR", **"-o"** "OUT_DIR" - output directory
+* **"--outdir"** "out_dir", **"-o"** "out_dir" - output directory
 
 * **"--in-dir"** "IN_DIR", **"-i"** "IN_DIR" - input directory
 

{sphinx_argparse_cli-1.22.0 → sphinx_argparse_cli-1.23.0}/tests/test_logic.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import os
+import re
 import sys
 from pathlib import Path
 from typing import TYPE_CHECKING
@@ -69,6 +70,24 @@ def test_hook(build_outcome: str) -> None:
     assert build_outcome
 
 
+@pytest.mark.sphinx(buildername="text", testroot="hook-intermixed")
+def test_hook_intermixed(build_outcome: str) -> None:
+    assert (
+        build_outcome
+        == """foo - CLI interface
+*******************
+
+   foo [--flag FLAG]
+
+
+foo options
+===========
+
+* **"--flag"** "FLAG" - a flag
+"""
+    )
+
+
 @pytest.mark.sphinx(buildername="text", testroot="hook-fail")
 def test_hook_fail(app: SphinxTestApp, warning: StringIO) -> None:
     app.build()
@@ -99,18 +118,18 @@ def test_set_description_as_text(build_outcome: str) -> None:
 
 @pytest.mark.sphinx(buildername="text", testroot="description-empty")
 def test_empty_description_as_text(build_outcome: str) -> None:
-    assert build_outcome == "foo - CLI interface\n*******************\n\n\n   foo\n"
+    assert build_outcome == "foo - CLI interface\n*******************\n\n   foo\n"
 
 
 @pytest.mark.sphinx(buildername="html", testroot="description-multiline")
 def test_multiline_description_as_html(build_outcome: str) -> None:
     ref = (
-        "This description\nspans multiple lines.\n\n  this line is indented.\n    and also this.\n\nNow this should be"
-        " a separate paragraph.\n"
+        "<pre><span></span>This description\nspans multiple lines.\n\n  this line is indented.\n    and also this.\n\n"
+        "Now this should be a separate paragraph.\n</pre>"
     )
     assert ref in build_outcome
 
-    ref = "This group description\n\nspans multiple lines.\n"
+    ref = "<pre><span></span>This group description\n\nspans multiple lines.\n</pre>"
     assert ref in build_outcome
 
 
@@ -121,14 +140,14 @@ def test_set_epilog_as_text(build_outcome: str) -> None:
 
 @pytest.mark.sphinx(buildername="text", testroot="epilog-empty")
 def test_empty_epilog_as_text(build_outcome: str) -> None:
-    assert build_outcome == "foo - CLI interface\n*******************\n\n   foo\n\n"
+    assert build_outcome == "foo - CLI interface\n*******************\n\n   foo\n"
 
 
 @pytest.mark.sphinx(buildername="html", testroot="epilog-multiline")
 def test_multiline_epilog_as_html(build_outcome: str) -> None:
     ref = (
-        "This epilog\nspans multiple lines.\n\n  this line is indented.\n    and also this.\n\nNow this should be"
-        " a separate paragraph.\n"
+        "<pre><span></span>This epilog\nspans multiple lines.\n\n  this line is indented.\n    and also this.\n\n"
+        "Now this should be a separate paragraph.\n</pre>"
     )
     assert ref in build_outcome
 
@@ -136,12 +155,58 @@ def test_multiline_epilog_as_html(build_outcome: str) -> None:
 @pytest.mark.sphinx(buildername="html", testroot="epilog-multiline-subclass")
 def test_multiline_epilog_subclass_formatter_as_html(build_outcome: str) -> None:
     ref = (
-        "This epilog\nspans multiple lines.\n\n  this line is indented.\n    and also this.\n\nNow this should be"
-        " a separate paragraph.\n"
+        "<pre><span></span>This epilog\nspans multiple lines.\n\n  this line is indented.\n    and also this.\n\n"
+        "Now this should be a separate paragraph.\n</pre>"
     )
     assert ref in build_outcome
 
 
+@pytest.mark.sphinx(buildername="text", testroot="subcommand-epilog-raw")
+def test_sub_command_description_epilog_as_text(build_outcome: str) -> None:
+    assert (
+        build_outcome
+        == """prog - CLI interface
+********************
+
+   prog {raw,plain} ...
+
+   root description
+     kept as is
+
+
+prog raw
+========
+
+   prog raw [--flag FLAG]
+
+   raw description
+     kept as is
+
+
+prog raw options
+----------------
+
+* **"--flag"** "FLAG" - raw flag
+
+   raw epilog
+     kept as is
+
+
+prog plain
+==========
+
+   prog plain
+
+plain description   reflowed
+
+plain epilog   reflowed
+
+   root epilog
+     kept as is
+"""
+    )
+
+
 @pytest.mark.sphinx(buildername="html", testroot="smartquotes")
 def test_option_dashes_survive_smartquotes(build_outcome: str) -> None:
     # option names mentioned in parser-supplied text keep their double hyphen
@@ -174,21 +239,97 @@ def test_set_usage_first(build_outcome: str) -> None:
     assert "complex first [-h]" in build_outcome.split("a-first-desc", maxsplit=1)[0]
 
 
+@pytest.mark.sphinx(buildername="text", testroot="help-apostrophe")
+def test_help_apostrophe(build_outcome: str, warning: StringIO) -> None:
+    assert (
+        build_outcome
+        == """prog - CLI interface
+********************
+
+   prog [--a A] [--b B]
+
+
+prog options
+============
+
+* **"--a"** "A" - don't use it's value
+
+* **"--b"** "B" - it's a "'thing'" to see
+"""
+    )
+    assert not warning.getvalue()
+
+
 @pytest.mark.sphinx(buildername="text", testroot="suppressed-action")
 def test_suppressed_action(build_outcome: str) -> None:
-    assert "--activities-since" not in build_outcome
+    assert (
+        build_outcome
+        == """foo - CLI interface
+*******************
+
+desc
+
+   foo
+"""
+    )
+
+
+@pytest.mark.sphinx(buildername="text", testroot="subparsers-positional")
+def test_subparsers_after_positional(build_outcome: str) -> None:
+    assert (
+        build_outcome
+        == """prog - CLI interface
+********************
+
+   prog root {run} ...
+
+
+prog positional arguments
+=========================
+
+* **"root"** - root positional
+
+
+prog root run
+=============
+
+   prog root run target {go} ...
+
+
+prog root run positional arguments
+----------------------------------
+
+* **"target"** - run positional
+
+
+prog root run target go
+=======================
+
+   prog root run target go [--flag FLAG]
+
+
+prog root run target go options
+-------------------------------
+
+* **"--flag"** "FLAG" - go flag
+"""
+    )
 
 
 @pytest.mark.parametrize(
     ("example", "output"),
     [
-        ("", ""),
-        ("{", "{"),
-        ('"', '"'),
-        ("'", "'"),
-        ("{a}", "``{a}``"),
-        ('"a"', '``"a"``'),
-        ("'a'", "``'a'``"),
+        pytest.param("", "", id="empty"),
+        pytest.param("{", "{", id="lone-brace"),
+        pytest.param('"', '"', id="lone-double-quote"),
+        pytest.param("'", "'", id="lone-single-quote"),
+        pytest.param("{a}", "``{a}``", id="braces"),
+        pytest.param('"a"', '``"a"``', id="double-quoted"),
+        pytest.param("'a'", "``'a'``", id="single-quoted"),
+        pytest.param("don't use it's value", "don't use it's value", id="apostrophes"),
+        pytest.param("it's a 'thing' to see", "it's a ``'thing'`` to see", id="apostrophe-and-quoted"),
+        pytest.param("'a' and 'b'", "``'a'`` and ``'b'``", id="two-quoted"),
+        pytest.param('say "hi" or "bye"', 'say ``"hi"`` or ``"bye"``', id="two-double-quoted"),
     ],
 )
 def test_help_loader(example: str, output: str) -> None:
@@ -215,6 +356,129 @@ def test_ref_prefix_doc(build_outcome: str) -> None:
     assert ref in build_outcome
 
 
+@pytest.mark.sphinx(buildername="html", testroot="option")
+def test_option_role_as_html(build_outcome: str, warning: StringIO) -> None:
+    hrefs = re.findall(r'<a class="reference internal" href="(#[^"]+)"><code class="xref std std-option', build_outcome)
+    assert hrefs == [
+        "#prog---root",
+        "#prog--r",
+        "#prog-run---magic",
+        "#prog-run-target",
+        "#prog-run---magic",
+        "#prog-run---magic",
+    ]
+    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 (
+        build_outcome
+        == """prog - CLI interface
+********************
+
+   prog [--flag FLAG] {run} ...
+
+
+prog options
+============
+
+* **"--flag"** "FLAG" - a flag
+
+
+prog run
+========
+
+   prog run [--magic MAGIC]
+
+
+prog run options
+----------------
+
+* **"--magic"** "MAGIC" - magic
+"""
+    )
+
+
+@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 (
+        build_outcome
+        == """prog - CLI interface
+********************
+
+   prog [--blank BLANK] [--list LIST] [--two TWO]
+
+
+prog options
+============
+
+* **"--blank"** "BLANK"
+
+* **"--list"** "LIST"
+
+  * item one
+
+  * item two
+
+* **"--two"** "TWO" - first paragraph
+
+  second paragraph
+"""
+    )
+
+
+@pytest.mark.sphinx(buildername="html", testroot="help-nodes")
+def test_help_nodes_as_html(build_outcome: str, warning: StringIO) -> None:
+    assert "<p></p>" not in build_outcome
+    assert not warning.getvalue()
+
+
+@pytest.mark.sphinx(buildername="html", testroot="group-untitled")
+def test_group_untitled(build_outcome: str, warning: StringIO) -> None:
+    headings = re.findall(r'<h2>(.*?)<a class="headerlink" href="(#[^"]+)"', build_outcome)
+    assert headings == [
+        ("tool options", "#tool-options"),
+        ("tool only a description", "#tool-only-a-description"),
+        ("tool another", "#tool-another"),
+        ("tool arguments", "#tool-arguments"),
+    ]
+    assert "<p>only a description</p>" not in build_outcome
+    assert not warning.getvalue()
+
+
 @pytest.mark.sphinx(buildername="text", testroot="ref-duplicate-label")
 def test_ref_duplicate_label(build_outcome: tuple[str, str], warning: StringIO) -> None:
     assert build_outcome
@@ -286,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")
@@ -323,6 +587,59 @@ def test_ref_cases(build_outcome: str, warning: StringIO) -> None:
     assert not warning.getvalue()
 
 
+@pytest.mark.sphinx(buildername="text", testroot="help-format-specifiers")
+def test_help_format_specifiers(build_outcome: str) -> None:
+    assert (
+        build_outcome
+        == """tool - CLI interface
+********************
+
+tool does things
+
+   tool [--n N] [--mode {a,b}] [--pct PCT] [--capital CAPITAL] [--kind KIND] [--level LEVEL]
+        {run} ...
+
+
+tool options
+============
+
+* **"--n"** "N" - count (default: 3)
+
+* **"--mode"** "{a,b}" - pick one of a, b (default: "a")
+
+* **"--pct"** "PCT" - 100% of tool (default: "5")
+
+* **"--capital"** "CAPITAL" - Default: 3
+
+* **"--kind"** "KIND" - parsed with float
+
+
+tool tuning
+===========
+
+tune tool
+
+* **"--level"** "LEVEL" - level (default: "1")
+
+
+tool run
+========
+
+tool run runs
+
+   tool run [--target TARGET]
+
+
+tool run options
+----------------
+
+* **"--target"** "TARGET" - target for tool run
+
+run tool --help
+"""
+    )
+
+
 @pytest.mark.sphinx(buildername="text", testroot="default-handling")
 def test_with_default(build_outcome: str) -> None:
     assert (
@@ -369,6 +686,13 @@ def test_subparsers(build_outcome: str) -> None:
     assert '<section id="test-no_child-options">' in build_outcome
 
 
+@pytest.mark.sphinx(buildername="html", testroot="subparsers-storeaction")
+def test_subparsers_stoeaction(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-positional-arguments">' in build_outcome
+
+
 @pytest.mark.sphinx(buildername="text", testroot="bad-module")
 def test_bad_module(app: SphinxTestApp, warning: StringIO) -> None:
     app.build()
@@ -391,6 +715,44 @@ def test_nargs(build_outcome: str) -> None:
     assert 'default: "None"' not in build_outcome
 
 
+@pytest.mark.sphinx(buildername="text", testroot="nargs-metavar")
+def test_nargs_metavar(build_outcome: str) -> None:
+    assert (
+        build_outcome
+        == """tool - CLI interface
+********************
+
+   tool [--opt [OPT]] [--many [MANY ...]] [--two TWO TWO] [--rest ...] [--out <file>]
+        [--dir path/to/dir] [--format {json,xml}]
+        SRC DST
+
+
+tool positional arguments
+=========================
+
+* **"SRC DST"** - copy pair
+
+
+tool options
+============
+
+* **"--opt"** "[OPT]" - optional value
+
+* **"--many"** "[MANY ...]" - zero or more
+
+* **"--two"** "TWO TWO" - exactly two
+
+* **"--rest"** "..." - the rest
+
+* **"--out"** "<file>" - output
+
+* **"--dir"** "path/to/dir" - dir
+
+* **"--format"** "{json,xml}" - output format
+"""
+    )
+
+
 @pytest.mark.sphinx(buildername="text", testroot="choices")
 def test_choices(build_outcome: str) -> None:
     assert "output format" in build_outcome

{sphinx_argparse_cli-1.22.0 → sphinx_argparse_cli-1.23.0}/pyproject.toml

@@ -136,10 +136,10 @@ environment.python-version = "3.14"
 
 [tool.coverage]
 run.parallel = true
+run.relative_files = true
 run.plugins = [
   "covdefaults",
 ]
-run.relative_files = true
 paths.source = [
   "src",
   "**/site-packages",