docs/_ext(fix[pretty_argparse]): Escape RST emphasis in argparse patterns

why: Patterns like `session-*` in argparse help trigger RST "Inline
emphasis start-string without end-string" warnings during Sphinx build.
what:
- Add escape_rst_emphasis() function to escape asterisks after hyphens
- Override _nested_parse_paragraph() to pre-escape before RST parsing
- Add 13 parameterized tests for escape_rst_emphasis behavior

Author: tony

docs/_ext/pretty_argparse.py

@@ -21,6 +21,44 @@
 
 _ANSI_RE = re.compile(r"\033\[[;?0-9]*[a-zA-Z]")
 
+# Match asterisks that trigger RST emphasis (preceded by delimiter like - or space)
+# but NOT asterisks already escaped or in code/literal contexts
+_RST_EMPHASIS_RE = re.compile(r"(?<=[^\s\\])-\*(?=[^\s*]|$)")
+
+
+def escape_rst_emphasis(text: str) -> str:
+    r"""Escape asterisks that would trigger RST inline emphasis.
+
+    In reStructuredText, ``*text*`` creates emphasis. When argparse help text
+    contains patterns like ``django-*``, the dash (a delimiter character) followed
+    by asterisk triggers emphasis detection, causing warnings like:
+    "Inline emphasis start-string without end-string."
+
+    This function escapes such asterisks with a backslash so they render literally.
+
+    Parameters
+    ----------
+    text : str
+        Text potentially containing problematic asterisks.
+
+    Returns
+    -------
+    str
+        Text with asterisks escaped where needed.
+
+    Examples
+    --------
+    >>> escape_rst_emphasis('tmuxp load "my-*"')
+    'tmuxp load "my-\\*"'
+    >>> escape_rst_emphasis("plain text")
+    'plain text'
+    >>> escape_rst_emphasis("already \\* escaped")
+    'already \\* escaped'
+    >>> escape_rst_emphasis("*emphasis* is ok")
+    '*emphasis* is ok'
+    """
+    return _RST_EMPHASIS_RE.sub(r"-\*", text)
+
 
 def strip_ansi(text: str) -> str:
     r"""Remove ANSI escape codes from text.
@@ -640,6 +678,16 @@ def _reorder_nodes(processed: list[nodes.Node]) -> list[nodes.Node]:
 class CleanArgParseDirective(ArgParseDirective):  # type: ignore[misc]
     """ArgParse directive that strips ANSI codes and formats examples."""
 
+    def _nested_parse_paragraph(self, text: str) -> nodes.Node:
+        """Parse text as RST, escaping problematic characters first.
+
+        Overrides the parent class to escape asterisks in patterns like
+        ``session-*`` that would otherwise trigger RST emphasis warnings.
+        """
+        escaped_text = escape_rst_emphasis(text)
+        result: nodes.Node = super()._nested_parse_paragraph(escaped_text)
+        return result
+
     def run(self) -> list[nodes.Node]:
         """Run the directive, clean output, format examples, and reorder."""
         result = super().run()

tests/docs/_ext/test_pretty_argparse.py

@@ -10,6 +10,7 @@
     _is_examples_section,
     _is_usage_block,
     _reorder_nodes,
+    escape_rst_emphasis,
     is_base_examples_term,
     is_examples_term,
     make_section_id,
@@ -83,6 +84,96 @@ def test_strip_ansi(test_id: str, input_text: str, expected: str) -> None:
     assert strip_ansi(input_text) == expected
 
 
+# --- escape_rst_emphasis tests ---
+
+
+class EscapeRstEmphasisFixture(t.NamedTuple):
+    """Test fixture for escape_rst_emphasis function."""
+
+    test_id: str
+    input_text: str
+    expected: str
+
+
+ESCAPE_RST_EMPHASIS_FIXTURES: list[EscapeRstEmphasisFixture] = [
+    EscapeRstEmphasisFixture(
+        test_id="glob_pattern_escaped",
+        input_text='tmuxp load "django-*"',
+        expected='tmuxp load "django-\\*"',
+    ),
+    EscapeRstEmphasisFixture(
+        test_id="multiple_glob_patterns",
+        input_text='tmuxp load "flask-*" "django-*"',
+        expected='tmuxp load "flask-\\*" "django-\\*"',
+    ),
+    EscapeRstEmphasisFixture(
+        test_id="plain_text_unchanged",
+        input_text="tmuxp load",
+        expected="tmuxp load",
+    ),
+    EscapeRstEmphasisFixture(
+        test_id="single_asterisk_unchanged",
+        input_text="tmuxp load *",
+        expected="tmuxp load *",
+    ),
+    EscapeRstEmphasisFixture(
+        test_id="emphasis_unchanged",
+        input_text="*emphasis* text",
+        expected="*emphasis* text",
+    ),
+    EscapeRstEmphasisFixture(
+        test_id="strong_unchanged",
+        input_text="**strong** text",
+        expected="**strong** text",
+    ),
+    EscapeRstEmphasisFixture(
+        test_id="already_escaped_unchanged",
+        input_text='tmuxp load "django-\\*"',
+        expected='tmuxp load "django-\\*"',
+    ),
+    EscapeRstEmphasisFixture(
+        test_id="hyphen_asterisk_space_unchanged",
+        input_text="- * bullet",
+        expected="- * bullet",
+    ),
+    EscapeRstEmphasisFixture(
+        test_id="glob_at_end_of_string",
+        input_text='Filter by "flask-*',
+        expected='Filter by "flask-\\*',
+    ),
+    EscapeRstEmphasisFixture(
+        test_id="underscore_asterisk_unchanged",
+        input_text='Use pattern "my_*"',
+        expected='Use pattern "my_*"',
+    ),
+    EscapeRstEmphasisFixture(
+        test_id="hyphen_escaped_underscore_unchanged",
+        input_text='"a-*" or "b_*" patterns',
+        expected='"a-\\*" or "b_*" patterns',
+    ),
+    EscapeRstEmphasisFixture(
+        test_id="empty_string",
+        input_text="",
+        expected="",
+    ),
+    EscapeRstEmphasisFixture(
+        test_id="asterisk_in_word_unchanged",
+        input_text="multi*plied value",
+        expected="multi*plied value",
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    EscapeRstEmphasisFixture._fields,
+    ESCAPE_RST_EMPHASIS_FIXTURES,
+    ids=[f.test_id for f in ESCAPE_RST_EMPHASIS_FIXTURES],
+)
+def test_escape_rst_emphasis(test_id: str, input_text: str, expected: str) -> None:
+    """Test RST emphasis escaping for glob patterns."""
+    assert escape_rst_emphasis(input_text) == expected
+
+
 # --- is_examples_term tests ---