Fix the MkDocs plugin and Sphinx directives

Author: kdeldycke

changelog.md

@@ -5,6 +5,8 @@
 > [!WARNING]
 > This version is **not released yet** and is under active development.
 
+- Fix the MkDocs plugin and Sphinx directives leaving Rich-based CLIs (such as `rich-click`) colorless in rendered documentation.
+
 ## [`7.20.0` (2026-06-17)](https://github.com/kdeldycke/click-extra/compare/v7.19.0...v7.20.0)
 
 - Add `MultiChoice` to `click_extra.types`: a Click `ParamType` for comma-separated multi-pick from a fixed set of values, the pick-many counterpart to `click.Choice`.

click_extra/colorize.py

@@ -27,7 +27,9 @@
 
 import os
 import re
+from collections.abc import Iterator
 from configparser import RawConfigParser
+from contextlib import contextmanager
 from dataclasses import dataclass, field, fields
 from enum import Enum
 from functools import lru_cache
@@ -120,6 +122,45 @@ def _nearest_256(r: int, g: int, b: int) -> int:
 """
 
 
+@contextmanager
+def forced_color() -> Iterator[None]:
+    """Force ANSI color while Click Extra captures CLI text for documentation.
+
+    Click Extra renders CLI help and output into docs from both the MkDocs plugin
+    (:mod:`click_extra.mkdocs`) and the Sphinx directives
+    (:mod:`click_extra.sphinx.click`). During a build that output is a pipe, not a TTY,
+    so the underlying renderers strip their escape codes. Two independent color systems
+    have to be defeated:
+
+    - Click's, gated by ``should_strip_ansi`` / ``ctx.color`` (what ``click.echo`` and
+      the Click and Click Extra help formatters consult). Sphinx's runner additionally
+      flips this one with ``click.testing.CliRunner(color=True)``.
+    - Rich's, gated by ``rich.console.Console.is_terminal``, which ignores the above and
+      reads ``FORCE_COLOR`` (https://force-color.org). This is the system ``rich-click``
+      uses, and ``color=True`` never reaches it.
+
+    ``FORCE_COLOR`` is the only signal common to both systems (Rich reads it directly;
+    Click Extra recognizes it through :data:`color_envvars`), so it is the lever we set
+    here. We also clear the color-disabling variables Click Extra recognizes
+    (``NO_COLOR``, ``LLM``, …) so an opt-out in the build environment cannot suppress the
+    rendering. The previous environment is restored on exit, so the override never leaks
+    beyond a single capture.
+    """
+    disabling = [var for var, enables in color_envvars.items() if not enables]
+    saved = {var: os.environ.get(var) for var in ("FORCE_COLOR", *disabling)}
+    os.environ["FORCE_COLOR"] = "1"
+    for var in disabling:
+        os.environ.pop(var, None)
+    try:
+        yield
+    finally:
+        for var, value in saved.items():
+            if value is None:
+                os.environ.pop(var, None)
+            else:
+                os.environ[var] = value
+
+
 class ColorOption(ExtraOption):
     """A pre-configured option that is adding a ``--color``/``--no-color`` (aliased by
     ``--ansi``/``--no-ansi``) to keep or strip colors and ANSI codes from CLI output.

click_extra/mkdocs.py

@@ -52,6 +52,7 @@
 
 import pymdownx.highlight
 
+from .colorize import forced_color
 from .pygments import AnsiHtmlFormatter
 
 ANSI_OUTPUT_FENCE = "```ansi-output"
@@ -82,9 +83,15 @@ def _ansi_lines(gen: Iterator[str]) -> Iterator[str]:
 def _patch_mkdocs_click() -> None:
     """Patch ``mkdocs-click`` code blocks to use the ``ansi-output`` lexer.
 
-    Wraps ``_make_usage`` and ``_make_plain_options`` so that their fenced
-    code blocks use the ANSI-aware lexer instead of plain ``text``.  The patch
-    is idempotent: calling it twice has no additional effect.
+    Wraps ``_make_usage`` and ``_make_plain_options`` so that their fenced code blocks
+    use the ANSI-aware lexer instead of plain ``text``, and so that the help they
+    capture is rendered with color forced on. ``mkdocs-click`` builds help from
+    ``ctx.make_formatter()`` rather than executing the command, so the environment
+    override (:func:`~click_extra.colorize.forced_color`) is the only lever available
+    here, and the capture is materialized inside it: the wrapped generators read their
+    formatter eagerly so the escape codes are produced while the override is active, not
+    lazily once the caller iterates and the environment has been restored. The patch is
+    idempotent: calling it twice has no additional effect.
     """
     try:
         from mkdocs_click import _docs
@@ -99,11 +106,15 @@ def _patch_mkdocs_click() -> None:
 
     @wraps(orig_usage)
     def _ansi_usage(*args, **kwargs):
-        return _ansi_lines(orig_usage(*args, **kwargs))
+        with forced_color():
+            lines = list(orig_usage(*args, **kwargs))
+        return _ansi_lines(iter(lines))
 
     @wraps(orig_plain)
     def _ansi_plain_options(*args, **kwargs):
-        return _ansi_lines(orig_plain(*args, **kwargs))
+        with forced_color():
+            lines = list(orig_plain(*args, **kwargs))
+        return _ansi_lines(iter(lines))
 
     _docs._make_usage = _ansi_usage
     _docs._make_plain_options = _ansi_plain_options

click_extra/sphinx/click.py

@@ -50,6 +50,7 @@
 from sphinx.directives.code import CodeBlock
 from sphinx.util import logging
 
+from ..colorize import forced_color
 from ._base import StatelessDomain, compile_directive, make_cleanup
 
 TYPE_CHECKING = False
@@ -131,7 +132,13 @@ class ClickRunner(CliRunner):
     """A sub-class of :class:`click.testing.CliRunner` for Sphinx directive execution.
 
     Produces unfiltered ANSI codes so that the ``Directive`` sub-classes below can
-    render colors in the HTML output.
+    render colors in the HTML output. Because Click Extra executes the documented
+    command here, :meth:`invoke` forces color across both color systems a CLI might use:
+    ``color=True`` covers Click's (``should_strip_ansi``), and
+    :func:`~click_extra.colorize.forced_color` sets ``FORCE_COLOR`` for Rich's (which
+    ``rich-click`` uses and ``color=True`` never reaches). The MkDocs plugin shares the
+    latter lever but cannot pass ``color=True``, since it patches a renderer it never
+    executes.
     """
 
     def __init__(self):
@@ -197,15 +204,22 @@ def invoke(  # type: ignore[override]
             if terminate_input:
                 input += "\x04"
 
-        result = super().invoke(
-            cli=cli,
-            args=args,
-            input=input,
-            env=env,
-            prog_name=prog_name,
-            color=True,
-            **extra,
-        )
+        # ``color=True`` keeps ANSI in Click's color system: it flips
+        # ``should_strip_ansi``, which CliRunner otherwise leaves stripping on its
+        # non-TTY buffer. But rich-click renders through Rich's Console, a separate
+        # system that ignores ``should_strip_ansi`` and only honors ``FORCE_COLOR``, so
+        # ``forced_color()`` sets that too. Together they cover both color systems a
+        # documented CLI might use.
+        with forced_color():
+            result = super().invoke(
+                cli=cli,
+                args=args,
+                input=input,
+                env=env,
+                prog_name=prog_name,
+                color=True,
+                **extra,
+            )
         # TODO: Maybe we can intercept the exception here either make it:
         # - part of the output in the rendered Sphinx code block, or
         # - re-raise it so Sphinx can display it properly in its logs.

tests/mkdocs/test_mkdocs.py

@@ -17,6 +17,7 @@
 
 from __future__ import annotations
 
+import os
 from textwrap import dedent
 
 import click
@@ -240,6 +241,44 @@ def test_patch_mkdocs_click_idempotent():
     assert _docs._make_plain_options is plain_fn
 
 
+@pytest.mark.usefixtures("_clean_mkdocs_click")
+def test_patch_mkdocs_click_forces_color_during_capture(monkeypatch):
+    """The patched generators capture help with color forced, even under ``NO_COLOR``.
+
+    Swapping the lexer to ``ansi-output`` is pointless if the captured help carries no
+    escape codes, which is exactly what happens when the build's stdout is a pipe. The
+    wrapper must therefore materialize the help *while* the color override is active.
+    Spying on ``make_formatter`` (where Rich and Click read the environment to decide on
+    color) proves ``FORCE_COLOR`` is set and the disabling vars are cleared at capture
+    time, and that the surrounding environment is restored once the capture completes.
+    """
+    from mkdocs_click import _docs
+
+    monkeypatch.setenv("NO_COLOR", "1")
+    monkeypatch.delenv("FORCE_COLOR", raising=False)
+
+    seen = {}
+    real_make_formatter = click.Context.make_formatter
+
+    def spy_make_formatter(self):
+        seen.setdefault("FORCE_COLOR", os.environ.get("FORCE_COLOR"))
+        seen.setdefault("NO_COLOR", os.environ.get("NO_COLOR"))
+        return real_make_formatter(self)
+
+    monkeypatch.setattr(click.Context, "make_formatter", spy_make_formatter)
+
+    _patch_mkdocs_click()
+    ctx = click.Context(_hello_cmd, info_name="hello")
+    list(_docs._make_usage(ctx))
+
+    # FORCE_COLOR was set (and NO_COLOR cleared) while the formatter was built...
+    assert seen["FORCE_COLOR"] == "1"
+    assert seen["NO_COLOR"] is None
+    # ...and the build environment is restored once the capture completes.
+    assert os.environ.get("FORCE_COLOR") is None
+    assert os.environ["NO_COLOR"] == "1"
+
+
 @pytest.mark.usefixtures("_clean_pymdownx", "_clean_mkdocs_click")
 def test_on_config_patches_mkdocs_click():
     """``on_config`` patches mkdocs-click alongside pymdownx.highlight."""

tests/sphinx/test_sphinx_click.py

@@ -964,3 +964,37 @@ def error_command(fail):
         + "Something went wrong!\n"
         + "</pre></div>"
     ) in html_output
+
+
+def test_clickrunner_forces_color(monkeypatch):
+    """``ClickRunner`` forces ``FORCE_COLOR`` so Rich-based CLIs colorize under ``NO_COLOR``.
+
+    The runner already passes ``color=True`` (Click's color system). But rich-click
+    renders help through Rich's ``Console``, gated on ``FORCE_COLOR``, which ``color=True``
+    never reaches. The runner therefore also forces ``FORCE_COLOR`` (clearing the
+    disabling vars) around the executed command, then restores the environment.
+    """
+    import os
+
+    import click
+
+    from click_extra.sphinx.click import ClickRunner
+
+    monkeypatch.setenv("NO_COLOR", "1")
+    monkeypatch.delenv("FORCE_COLOR", raising=False)
+
+    seen = {}
+
+    @click.command()
+    def probe():
+        seen["FORCE_COLOR"] = os.environ.get("FORCE_COLOR")
+        seen["NO_COLOR"] = os.environ.get("NO_COLOR")
+
+    ClickRunner().invoke(probe, [])
+
+    # Color was forced through Rich's system while the command ran...
+    assert seen["FORCE_COLOR"] == "1"
+    assert seen["NO_COLOR"] is None
+    # ...and the build environment is restored afterwards.
+    assert os.environ.get("FORCE_COLOR") is None
+    assert os.environ["NO_COLOR"] == "1"

tests/test_colorize.py

@@ -55,6 +55,7 @@
 from click_extra.colorize import (
     HelpKeywords,
     color_envvars,
+    forced_color,
     highlight,
 )
 from click_extra.pytest import (
@@ -2553,3 +2554,24 @@ def standalone_help():
         )
     assert result.exit_code == 0
     assert not result.stderr
+
+
+def test_forced_color_sets_and_restores_env(monkeypatch):
+    """``forced_color`` forces ``FORCE_COLOR`` and clears Click Extra's disabling vars.
+
+    Inside the context the capture sees ``FORCE_COLOR=1`` with every flag that would
+    disable color (``NO_COLOR``, ``LLM``, …) removed; on exit the prior environment,
+    including any pre-existing values, is restored untouched.
+    """
+    monkeypatch.setenv("NO_COLOR", "1")
+    monkeypatch.setenv("LLM", "1")
+    monkeypatch.delenv("FORCE_COLOR", raising=False)
+
+    with forced_color():
+        assert os.environ["FORCE_COLOR"] == "1"
+        assert "NO_COLOR" not in os.environ
+        assert "LLM" not in os.environ
+
+    assert "FORCE_COLOR" not in os.environ
+    assert os.environ["NO_COLOR"] == "1"
+    assert os.environ["LLM"] == "1"