🐛 fix(smartquotes): prevent --option names from being rewritten to en dashes (#322)

Option names mentioned in parser-supplied text - descriptions, epilogs,
and help strings - had their leading `--` rewritten to an en dash in the
rendered HTML, so a flag documented as `--text` displayed as `–text`.
Readers copying the option out of the docs got something the command
line no longer accepts.

Each `--option` token in parser-supplied text is now wrapped in an
inline node that opts out via support_smartquotes, so smart quotes skips
it while the surrounding prose keeps normal typography.

Fixes #321

Author: mmulqueen

CHANGELOG.md

@@ -7,6 +7,8 @@ All notable changes to this project will be documented in this file.
 - Allow to add content to directive.
 - Fix Sphinx warnings about parallel reads.
 - Add `force_args_lower` to enable `:ref:` links with mixed-case program names and arguments.
+- `--option` names mentioned in descriptions, epilogs, and help text keep their double hyphen instead of being rewritten
+  to an en dash by Sphinx's smart quotes transform; the surrounding text keeps normal typography.
 
 ## 1.13.1
 

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

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

roots/test-smartquotes/parser.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser
+
+
+def make() -> ArgumentParser:
+    parser = ArgumentParser(
+        prog="smartquotes",
+        description="Pass input via --text or stdin.",
+        epilog="Read the --text docs; see also --2fa and --dry_run.",
+    )
+    parser.add_argument("--text", help="text to encode; combine with --output for files")
+    parser.add_argument(
+        "--typography", help="typography still applies to non-options like these north--south and 10--20"
+    )
+    sub = parser.add_subparsers()
+    sub.add_parser("build", help="build things with --flair")
+    return parser

src/sphinx_argparse_cli/_logic.py

@@ -22,11 +22,13 @@
 
 from docutils.nodes import (
     Element,
+    FixedTextElement,
     Node,
     Text,
     bullet_list,
     container,
     fully_normalize_name,
+    inline,
     list_item,
     literal,
     literal_block,
@@ -228,7 +230,9 @@ def _pre_format(self, block: None | str) -> None | paragraph | literal_block:
             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"]
@@ -302,6 +306,7 @@ def _mk_option_line(self, action: Action, prefix: str) -> list_item:
             line += Text(" (default: ")
             line += literal(text=str(action.default).replace(str(Path.cwd()), "{cwd}"))
             line += Text(")")
+        _protect_option_dashes(line)
         return point
 
     def _mk_option_name(self, line: paragraph, prefix: str, opt: str) -> None:
@@ -365,6 +370,7 @@ def _mk_sub_command(self, aliases: list[str], help_msg: str, parser: ArgumentPar
         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:
@@ -444,6 +450,38 @@ def load_help_text(help_text: str) -> str:
     return CURLY_BRACES.sub("``{\\1}``", double_quote)
 
 
+_OPTION_TOKEN = re.compile(r"((?<!\w)--[a-zA-Z0-9][\w-]*)")
+
+
+def _protect_option_dashes(node: Element) -> None:
+    """
+    Wrap ``--option`` tokens so smart quotes can't rewrite their ``--`` to an en dash.
+
+    Each token becomes an inline exempted via ``support_smartquotes``; surrounding text is
+    left untouched. The node is modified in place.
+    """
+    for text in list(node.findall(Text)):
+        parent = text.parent
+        if isinstance(parent, (literal, FixedTextElement)):
+            continue
+        # Capturing group => split() yields the option tokens at odd indices,
+        # interleaved with the surrounding text.
+        parts = _OPTION_TOKEN.split(text)
+        if len(parts) == 1:
+            continue
+        replacement: list[Node] = []
+        for i, part in enumerate(parts):
+            if not part:
+                continue
+            if i % 2:
+                inline_node = inline("", part)
+                inline_node["support_smartquotes"] = False
+                replacement.append(inline_node)
+            else:
+                replacement.append(Text(part))
+        parent.replace(text, replacement)
+
+
 class HookError(Exception):
     def __init__(self, parser: ArgumentParser) -> None:
         self.parser = parser

tests/test_logic.py

@@ -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: