Strip rich-click markup from structured CLI help

Author: smprather

great_docs/core.py

@@ -4420,6 +4420,40 @@ def _get_cli_entry_point_name(self, package_name: str) -> str | None:
 
         return None
 
+    @staticmethod
+    def _strip_rich_click_markup(text: str, cmd) -> str:
+        """Strip rich-click markup when the command renders ``--help`` with it.
+
+        Rich-click interprets ``[b]...[/]`` and similar tags when its effective
+        ``text_markup`` mode is ``"rich"``. Structured fields written into the
+        generated page must be plain text; the full ``--help`` block is already
+        rendered by Click and is left alone. Commands from plain Click, Typer,
+        or rich-click's ``markdown``/``ansi`` modes keep their text unchanged.
+        """
+        if not text:
+            return text
+
+        try:
+            from rich.text import Text
+            from rich_click import RichCommand
+        except ImportError:
+            return text
+
+        if not isinstance(cmd, RichCommand):
+            return text
+
+        try:
+            formatter = cmd.context_class(cmd, info_name="").make_formatter()
+            if formatter.config.text_markup != "rich":
+                return text
+        except Exception:  # pragma: no cover - optional dependency internals
+            return text
+
+        try:
+            return Text.from_markup(text).plain
+        except Exception:  # pragma: no cover - malformed markup is left as-is
+            return text
+
     def _extract_click_command(self, cmd, name: str, parent_path: str = "") -> dict:
         """
         Extract information from a Click command or group.
@@ -4454,25 +4488,29 @@ def _extract_click_command(self, cmd, name: str, parent_path: str = "") -> dict:
             if kind == "option":
                 opt_info = self._extract_click_option(param)
                 if opt_info:
+                    opt_info["help"] = self._strip_rich_click_markup(opt_info["help"], cmd)
                     options.append(opt_info)
             elif kind == "argument":
                 arg_info = self._extract_click_argument(param)
                 if arg_info:
                     arguments.append(arg_info)
 
+        command_help = self._strip_rich_click_markup(cmd.help or "", cmd)
+
         # Parse description and examples from the help text
-        description, examples = self._parse_click_help_parts(cmd.help or "")
+        description, examples = self._parse_click_help_parts(command_help)
 
         # Extract the short help (Click may auto-derive it, but sometimes it's
         # empty for subcommands).  Fall back to the first line/sentence of help.
         short_help = getattr(cmd, "short_help", "") or ""
-        if not short_help and cmd.help:
+        if not short_help and command_help:
             short_help = cmd.get_short_help_str(limit=150)
+        short_help = self._strip_rich_click_markup(short_help, cmd)
 
         info = {
             "name": name,
             "full_path": full_path,
-            "help": cmd.help or "",
+            "help": command_help,
             "short_help": short_help,
             "help_text": help_text,  # The actual --help output
             "deprecated": getattr(cmd, "deprecated", False),

pyproject.toml

@@ -71,6 +71,7 @@ dev = [
     "build>=0.7",
     "twine>=3.4",
     "typer>=0.12.0",
+    "rich-click>=1.9.8",
     "great-docs[docs]",
 ]
 docs = [

tests/test_cli_help_markup.py

@@ -0,0 +1,91 @@
+"""Structured CLI help must not contain rich-click markup.
+
+Rich-click renders ``[b]...[/]`` and ``[cyan]...[/]`` in ``--help``. The
+structured option/command fields are written into Quarto pages, where those
+tags would appear literally, so extraction has to strip them when rich markup
+is active.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+import pytest
+
+from great_docs import GreatDocs
+
+rich_click = pytest.importorskip("rich_click")
+
+
+def _make_gd(tmp_path: Path) -> GreatDocs:
+    (tmp_path / "great-docs.yml").write_text("module: mypkg\n", encoding="utf-8")
+    return GreatDocs(project_path=str(tmp_path))
+
+
+def test_rich_click_option_help_is_plain(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(rich_click.rich_click, "TEXT_MARKUP", "rich")
+
+    @rich_click.command()
+    @rich_click.option(
+        "--dev",
+        is_flag=True,
+        help="Add a [b]Dump Debug[/] button in [cyan]/tmp[/].",
+    )
+    def main(dev: bool) -> None:
+        """Demo command."""
+
+    info = _make_gd(tmp_path)._extract_click_command(main, "demo")
+
+    assert info["options"][0]["help"] == "Add a Dump Debug button in /tmp."
+
+
+def test_rich_click_command_help_is_plain(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(rich_click.rich_click, "TEXT_MARKUP", "rich")
+
+    @rich_click.command()
+    def main() -> None:
+        """Say [b]hello[/] to [cyan]everyone[/]."""
+
+    info = _make_gd(tmp_path)._extract_click_command(main, "demo")
+
+    assert info["help"] == "Say hello to everyone."
+    assert info["short_help"] == "Say hello to everyone."
+    assert info["description"] == "Say hello to everyone."
+
+
+def test_rich_click_ansi_markup_is_kept(tmp_path: Path) -> None:
+    @rich_click.command()
+    @rich_click.option("--value", help="Literal [b] bracket.")
+    def main(value: str) -> None:
+        """Demo command."""
+
+    info = _make_gd(tmp_path)._extract_click_command(main, "demo")
+
+    assert info["options"][0]["help"] == "Literal [b] bracket."
+
+
+def test_plain_click_help_keeps_brackets(tmp_path: Path) -> None:
+    @click.command()
+    @click.option("--value", help="Default is [default: 1].")
+    def main(value: str) -> None:
+        """Demo command."""
+
+    info = _make_gd(tmp_path)._extract_click_command(main, "demo")
+
+    assert info["options"][0]["help"] == "Default is [default: 1]."
+
+
+def test_rich_click_markdown_markup_is_kept(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr(rich_click.rich_click, "TEXT_MARKUP", "markdown")
+
+    @rich_click.command()
+    @rich_click.option("--value", help="Literal [b] bracket and **bold**.")
+    def main(value: str) -> None:
+        """Demo command."""
+
+    info = _make_gd(tmp_path)._extract_click_command(main, "demo")
+
+    assert info["options"][0]["help"] == "Literal [b] bracket and **bold**."