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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-argparse-cli
-Version: 1.21.3
+Version: 1.22.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
@@ -22,6 +22,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Topic :: Documentation
 Classifier: Topic :: Documentation :: Sphinx
@@ -63,7 +64,7 @@ Use the directive in any reStructuredText file:
 ```
 
 `:module:` points to the Python module containing the parser, and `:func:` names a zero-argument function that returns
-an `ArgumentParser`. Build your docs and the full CLI reference appears automatically.
+an `ArgumentParser`. Build your docs and the full CLI reference appears.
 
 ## How-to guides
 
@@ -129,7 +130,7 @@ Set the character width for usage lines and optionally show usage before the des
 
 ### Override title, description, or epilog
 
-Replace auto-detected values, or pass an empty string to suppress them entirely:
+Replace auto-detected values, or pass an empty string to suppress them:
 
 ```rst
 .. sphinx_argparse_cli::
@@ -166,7 +167,7 @@ The anchor text is visible after the `#` in the URL when you click a heading.
 ### Handle mixed-case references
 
 Sphinx `:ref:` only supports lower-case targets. When your program name or flags contain capital letters, set
-`:force_refs_lower:` to convert them — each upper-case letter becomes its lower-case form prefixed with `_` (e.g. `A`
+`:force_refs_lower:` to convert them. Each upper-case letter becomes its lower-case form prefixed with `_` (e.g. `A`
 becomes `_a`):
 
 ```rst

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

@@ -32,7 +32,7 @@ Use the directive in any reStructuredText file:
 ```
 
 `:module:` points to the Python module containing the parser, and `:func:` names a zero-argument function that returns
-an `ArgumentParser`. Build your docs and the full CLI reference appears automatically.
+an `ArgumentParser`. Build your docs and the full CLI reference appears.
 
 ## How-to guides
 
@@ -98,7 +98,7 @@ Set the character width for usage lines and optionally show usage before the des
 
 ### Override title, description, or epilog
 
-Replace auto-detected values, or pass an empty string to suppress them entirely:
+Replace auto-detected values, or pass an empty string to suppress them:
 
 ```rst
 .. sphinx_argparse_cli::
@@ -135,7 +135,7 @@ The anchor text is visible after the `#` in the URL when you click a heading.
 ### Handle mixed-case references
 
 Sphinx `:ref:` only supports lower-case targets. When your program name or flags contain capital letters, set
-`:force_refs_lower:` to convert them — each upper-case letter becomes its lower-case form prefixed with `_` (e.g. `A`
+`:force_refs_lower:` to convert them. Each upper-case letter becomes its lower-case form prefixed with `_` (e.g. `A`
 becomes `_a`):
 
 ```rst

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

@@ -2,7 +2,7 @@
 build-backend = "hatchling.build"
 requires = [
   "hatch-vcs>=0.5",
-  "hatchling>=1.28",
+  "hatchling>=1.30.1",
 ]
 
 [project]
@@ -31,6 +31,7 @@ classifiers = [
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
   "Programming Language :: Python :: Implementation :: CPython",
   "Topic :: Documentation",
   "Topic :: Documentation :: Sphinx",
@@ -56,29 +57,29 @@ dev = [
 test = [
   "covdefaults>=2.3",
   "defusedxml>=0.7.1",
-  "pytest>=9.0.2",
-  "pytest-cov>=7",
+  "pytest>=9.1.1",
+  "pytest-cov>=7.1",
 ]
 type = [
-  "ty>=0.0.17",
+  "ty<0.0.25,>=0.0.24",
   { include-group = "test" },
 ]
 lint = [
-  "pre-commit-uv>=4.2",
+  "pre-commit-uv>=4.2.2",
 ]
 pkg-meta = [
   "check-wheel-contents>=0.6.3",
   "twine>=6.2",
-  "uv>=0.10.2",
+  "uv>=0.11.26",
 ]
 
 [tool.hatch]
+version.source = "vcs"
 build.hooks.vcs.version-file = "src/sphinx_argparse_cli/version.py"
 build.targets.sdist.include = [
   "/src",
   "/tests",
 ]
-version.source = "vcs"
 
 [tool.black]
 line-length = 120
@@ -128,7 +129,10 @@ builtin = "clear,usage,en-GB_to_en-US"
 count = true
 
 [tool.pyproject-fmt]
-max_supported_python = "3.14"
+max_supported_python = "3.15"
+
+[tool.ty]
+environment.python-version = "3.14"
 
 [tool.coverage]
 run.parallel = true
@@ -143,6 +147,3 @@ paths.source = [
 report.fail_under = 100
 html.show_contexts = true
 html.skip_covered = false
-
-[tool.ty]
-environment.python-version = "3.14"

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

@@ -17,16 +17,18 @@ from argparse import (
 from collections import defaultdict
 from contextlib import contextmanager
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, ClassVar, NamedTuple, cast
+from typing import TYPE_CHECKING, Any, ClassVar, Final, cast
 from unittest.mock import patch
 
 from docutils.nodes import (
     Element,
+    FixedTextElement,
     Node,
     Text,
     bullet_list,
     container,
     fully_normalize_name,
+    inline,
     list_item,
     literal,
     literal_block,
@@ -48,22 +50,10 @@ if TYPE_CHECKING:
 
     from docutils.parsers.rst.states import RSTState, RSTStateMachine
     from sphinx.domains.std import StandardDomain
+    from sphinx.util.logging import SphinxLoggerAdapter
 
 
-class TextAsDefault(NamedTuple):
-    text: str
-
-
-def make_id(key: str) -> str:
-    return "-".join(key.split()).rstrip("-")
-
-
-def make_id_lower(key: str) -> str:
-    # replace all capital letters "X" with "_lower(X)"
-    return re.sub("[A-Z]", lambda m: "_" + m.group(0).lower(), make_id(key))
-
-
-logger = getLogger(__name__)
+_LOGGER: Final[SphinxLoggerAdapter] = getLogger(__name__)
 
 
 class SphinxArgparseCli(SphinxDirective):
@@ -82,9 +72,8 @@ class SphinxArgparseCli(SphinxDirective):
         "group_title_prefix": unchanged,
         "group_sub_title_prefix": unchanged,
         "no_default_values": unchanged,
-        # :ref: only supports lower-case.  If this is set, any
-        # would-be-upper-case chars will be prefixed with _.  Since
-        # this is backwards incompatible for URL's, this is opt-in.
+        # :ref: only supports lower-case, so this prefixes would-be-upper-case chars with _;
+        # opt-in because it breaks existing URLs.
         "force_refs_lower": flag,
     }
 
@@ -106,7 +95,7 @@ class SphinxArgparseCli(SphinxDirective):
         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
+        self._make_id = make_id_lower if "force_refs_lower" in self.options else make_id
 
     @property
     def parser(self) -> ArgumentParser:
@@ -153,10 +142,8 @@ class SphinxArgparseCli(SphinxDirective):
         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] = {}
         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():
@@ -170,28 +157,24 @@ class SphinxArgparseCli(SphinxDirective):
             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] = 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]]:
+    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]
-        sub_parser = top_sub_parser._group_actions[0]  # type: ignore[assignment]  # noqa: SLF001
-
+        sub_parser: _SubParsersAction[ArgumentParser] = 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
+        self.env.note_reread()  # this document needs to always be rebuilt
         title_text = self.options.get("title", f"{self.parser.prog} - CLI interface").strip()
         if not title_text:
             home_section: Element = container("")
         else:
-            home_section = section("", title("", Text(title_text)), ids=[self.make_id(title_text)], names=[title_text])
+            home_section = section("", title("", Text(title_text)), ids=[self._make_id(title_text)], names=[title_text])
 
         if "usage_first" in self.options:
             home_section += self._mk_usage(self.parser)
@@ -202,15 +185,13 @@ class SphinxArgparseCli(SphinxDirective):
         if "usage_first" not in self.options:
             home_section += self._mk_usage(self.parser)
 
-        # construct groups excluding sub-parsers
         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]
             )
-        # construct sub-parser
-        for aliases, help_msg, parser in self.load_sub_parsers():
+        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)):
@@ -228,14 +209,16 @@ class SphinxArgparseCli(SphinxDirective):
             lit = literal_block("", Text(block), classes=["sphinx-argparse-cli-wrap"])
             lit["language"] = "none"
             return lit
-        return paragraph("", Text(block))
+        para = paragraph("", Text(block))
+        _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}"
-        ref_id = self.make_id(title_ref)
+        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])
@@ -265,15 +248,11 @@ class SphinxArgparseCli(SphinxDirective):
         if action.metavar:
             as_key = action.metavar if isinstance(action.metavar, str) else action.metavar[0]
         if action.option_strings:
-            first = True
-            is_flag = action.nargs == 0
-            for opt in action.option_strings:
-                if first:
-                    first = False
-                else:
+            for at, opt in enumerate(action.option_strings):
+                if at:
                     line += Text(", ")
                 self._mk_option_name(line, prefix, opt)
-                if not is_flag:
+                if action.nargs != 0:
                     line += Text(" ")
                     metavar_text = (
                         " ".join(meta.upper() for meta in action.metavar)
@@ -284,7 +263,6 @@ class SphinxArgparseCli(SphinxDirective):
         else:
             self._mk_option_name(line, prefix, as_key)
 
-        point = list_item("", line, ids=[])
         if action.help:
             help_text = load_help_text(action.help)
             temp = paragraph()
@@ -302,16 +280,15 @@ class SphinxArgparseCli(SphinxDirective):
             line += Text(" (default: ")
             line += literal(text=str(action.default).replace(str(Path.cwd()), "{cwd}"))
             line += Text(")")
-        return point
+        _protect_option_dashes(line)
+        return list_item("", line, ids=[])
 
     def _mk_option_name(self, line: paragraph, prefix: str, opt: str) -> None:
-        ref_id = self.make_id(f"{prefix}-{opt}")
+        ref_id = self._make_id(f"{prefix}-{opt}")
         ref_title = f"{prefix} {opt}"
         ref = reference("", refid=ref_id, reftitle=ref_title)
         line.attributes["ids"].append(ref_id)
-        st = strong()
-        st += literal(text=opt)
-        ref += st
+        ref += strong("", "", literal(text=opt))
         self._register_ref(ref_id, ref_title, ref, is_cli_option=True)
         line += ref
 
@@ -329,7 +306,7 @@ class SphinxArgparseCli(SphinxDirective):
         else:
             name = normalize_name(ref_name)
         if name in self._std_domain.labels:
-            logger.warning(
+            _LOGGER.warning(
                 __("duplicate label %s, other instance in %s"),
                 name,
                 self.env.doc2path(self._std_domain.labels[name][0]),
@@ -355,7 +332,7 @@ class SphinxArgparseCli(SphinxDirective):
             title_text += aliases_text
             title_ref += aliases_text
         title_text = title_text.strip()
-        ref_id = self.make_id(title_ref)
+        ref_id = self._make_id(title_ref)
         group_section = section("", title("", Text(title_text)), ids=[ref_id], names=[title_ref])
         self._register_ref(ref_id, title_ref, group_section)
 
@@ -365,16 +342,16 @@ class SphinxArgparseCli(SphinxDirective):
         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 "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:  # do not show empty groups  # noqa: SLF001
+            if not group._group_actions:  # 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, prog=self.parser.prog.split("/")[-1])
         return group_section
@@ -415,33 +392,64 @@ class SphinxArgparseCli(SphinxDirective):
     @staticmethod
     def _apply_sub_title(title_text: str, sub_title_prefix: str, prog: str, sub_cmd: str) -> str:
         if sub_title_prefix:
-            sub_title_prefix = sub_title_prefix.replace("{prog}", prog)
-            sub_title_prefix = sub_title_prefix.replace("{subcommand}", sub_cmd)
+            sub_title_prefix = sub_title_prefix.replace("{prog}", prog).replace("{subcommand}", sub_cmd)
             title_text += f"{sub_title_prefix} "
         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():
+        with 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]:
+    def _no_color(self) -> Iterator[None]:
         with patch.dict(os.environ, {"NO_COLOR": "1"}, clear=False):
-            yield None
+            yield
 
 
-SINGLE_QUOTE = re.compile(r"[']+(.+?)[']+")
-DOUBLE_QUOTE = re.compile(r'["]+(.+?)["]+')
-CURLY_BRACES = re.compile(r"[{](.+?)[}]")
+def make_id_lower(key: str) -> str:
+    return re.sub("[A-Z]", lambda m: f"_{m.group(0).lower()}", make_id(key))
+
+
+def make_id(key: str) -> str:
+    return "-".join(key.split()).rstrip("-")
+
+
+_HELP_SUBSTITUTIONS: Final[list[tuple[re.Pattern[str], str]]] = [
+    (re.compile(r"[']+(.+?)[']+"), "``'\\1'``"),
+    (re.compile(r'["]+(.+?)["]+'), '``"\\1"``'),
+    (re.compile(r"[{](.+?)[}]"), "``{\\1}``"),
+]
 
 
 def load_help_text(help_text: str) -> str:
-    single_quote = SINGLE_QUOTE.sub("``'\\1'``", help_text)
-    double_quote = DOUBLE_QUOTE.sub('``"\\1"``', single_quote)
-    return CURLY_BRACES.sub("``{\\1}``", double_quote)
+    for pattern, replacement in _HELP_SUBSTITUTIONS:
+        help_text = pattern.sub(replacement, help_text)
+    return help_text
+
+
+_OPTION_TOKEN: Final[re.Pattern[str]] = re.compile(r"((?<!\w)--[a-zA-Z0-9][\w-]*)")
+
+
+def _protect_option_dashes(node: Element) -> None:
+    """Wrap each ``--option`` in a smartquotes-exempt inline so its ``--`` survives Sphinx's en-dash transform."""
+    for text in list(node.findall(Text)):
+        if isinstance(text.parent, (literal, FixedTextElement)):
+            continue
+        # A capturing group makes split() interleave the option tokens (odd indices) with the surrounding text.
+        parts = _OPTION_TOKEN.split(text)
+        if len(parts) == 1:
+            continue
+        text.parent.replace(
+            text,
+            [
+                inline("", part, support_smartquotes=False) if index % 2 else Text(part)
+                for index, part in enumerate(parts)
+                if part
+            ],
+        )
 
 
 class HookError(Exception):
@@ -453,7 +461,7 @@ def _parse_known_args_hook(self: ArgumentParser, *args: Any, **kwargs: Any) -> N
     raise HookError(self)
 
 
-_ANSI_COLOR_RE = re.compile(r"\x1b\[[0-9;]*m")
+_ANSI_COLOR_RE: Final[re.Pattern[str]] = re.compile(r"\x1b\[[0-9;]*m")
 
 
 def _strip_ansi_colors(text: str) -> str:  # pragma: >=3.14 cover

sphinx_argparse_cli-1.22.0/src/sphinx_argparse_cli/version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+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)
+
+__commit_id__ = commit_id = None

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

@@ -7,7 +7,7 @@ from typing import TYPE_CHECKING
 
 import pytest
 
-from sphinx_argparse_cli._logic import make_id, make_id_lower
+from sphinx_argparse_cli._logic import load_help_text, make_id, make_id_lower
 
 if TYPE_CHECKING:
     from io import StringIO
@@ -142,6 +142,19 @@ def test_multiline_epilog_subclass_formatter_as_html(build_outcome: str) -> None
     assert ref in build_outcome
 
 
+@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
+    assert "Pass input via <span>--text</span> or stdin." in build_outcome
+    assert "see also <span>--2fa</span> and <span>--dry_run</span>." in build_outcome
+    assert "combine with <span>--output</span> for files" in build_outcome
+    assert "build things with <span>--flair</span>" in build_outcome
+    for mangled in ("\u2013text", "\u2013output", "\u20132fa", "\u2013dry_run", "\u2013flair"):
+        assert mangled not in build_outcome
+    # the surrounding text keeps normal typography
+    assert "north\u2013south and 10\u201320" in build_outcome
+
+
 @pytest.mark.sphinx(buildername="text", testroot="complex")
 @pytest.mark.prepare(directive_args=[":usage_width: 100"])
 def test_usage_width_default(build_outcome: str) -> None:
@@ -179,10 +192,7 @@ def test_suppressed_action(build_outcome: str) -> None:
     ],
 )
 def test_help_loader(example: str, output: str) -> None:
-    from sphinx_argparse_cli._logic import load_help_text  # noqa: PLC0415
-
-    result = load_help_text(example)
-    assert result == output
+    assert load_help_text(example) == output
 
 
 @pytest.mark.sphinx(buildername="html", testroot="ref")

{sphinx_argparse_cli-1.21.3 → sphinx_argparse_cli-1.22.0}/tests/test_sphinx_argparse_cli.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
+import sphinx_argparse_cli
 
-def test_version() -> None:
-    import sphinx_argparse_cli  # noqa: PLC0415
 
+def test_version() -> None:
     assert sphinx_argparse_cli.__version__

sphinx_argparse_cli-1.21.3/src/sphinx_argparse_cli/version.py

@@ -1,34 +0,0 @@
-# file generated by setuptools-scm
-# don't change, don't track in version control
-
-__all__ = [
-    "__version__",
-    "__version_tuple__",
-    "version",
-    "version_tuple",
-    "__commit_id__",
-    "commit_id",
-]
-
-TYPE_CHECKING = False
-if TYPE_CHECKING:
-    from typing import Tuple
-    from typing import Union
-
-    VERSION_TUPLE = Tuple[Union[int, str], ...]
-    COMMIT_ID = Union[str, None]
-else:
-    VERSION_TUPLE = object
-    COMMIT_ID = object
-
-version: str
-__version__: str
-__version_tuple__: VERSION_TUPLE
-version_tuple: VERSION_TUPLE
-commit_id: COMMIT_ID
-__commit_id__: COMMIT_ID
-
-__version__ = version = '1.21.3'
-__version_tuple__ = version_tuple = (1, 21, 3)
-
-__commit_id__ = commit_id = None