🐛 fix: set PYTHON_COLORS=0 while formatting usage

On Python 3.14 argparse checks PYTHON_COLORS before NO_COLOR, so a doc
build with PYTHON_COLORS=1 kept coloring the usage text and the
`usage: ` prefix slice removed the wrong characters. Setting both
variables during format_usage yields plain output in every shell.

Author: gaborbernat

CHANGELOG.md

@@ -9,6 +9,7 @@ All notable changes to this project will be documented in this file.
 - Add `force_refs_lower` to enable `:ref:` links with mixed-case program names and arguments.
 - Fix Sphinx smart quotes rewriting `--` to an en dash in `--option` names within descriptions, epilogs, and help text.
 - Register flags and positional arguments as Sphinx program options so the `:option:` role links to them.
+- Keep ANSI color codes out of usage blocks when `PYTHON_COLORS=1` is set on Python 3.14 or newer.
 
 ## 1.13.1
 

roots/test-python-colors/conf.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+os.environ["PYTHON_COLORS"] = "1"
+extensions = ["sphinx_argparse_cli"]
+nitpicky = True

roots/test-python-colors/index.rst

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

roots/test-python-colors/parser.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser
+
+
+def make() -> ArgumentParser:
+    parser = ArgumentParser(prog="prog", add_help=False)
+    parser.add_argument("--flag", help="a flag")
+    parser.add_subparsers().add_parser("run", add_help=False).add_argument("--magic", help="magic")
+    return parser

src/sphinx_argparse_cli/_logic.py

@@ -398,7 +398,8 @@ def _mk_usage(self, parser: ArgumentParser) -> literal_block:
 
     @contextmanager
     def _no_color(self) -> Iterator[None]:
-        with patch.dict(os.environ, {"NO_COLOR": "1"}, clear=False):
+        # PYTHON_COLORS=1 outranks NO_COLOR in argparse, so both must be set to get plain text
+        with patch.dict(os.environ, {"NO_COLOR": "1", "PYTHON_COLORS": "0"}, clear=False):
             yield
 
 

tests/test_logic.py

@@ -230,6 +230,36 @@ def test_option_role_as_html(build_outcome: str, warning: StringIO) -> None:
     assert not warning.getvalue()
 
 
+@pytest.mark.sphinx(buildername="text", testroot="python-colors")
+def test_usage_ignores_python_colors(build_outcome: str) -> None:
+    assert (
+        build_outcome
+        == """prog - CLI interface
+********************
+
+   prog [--flag FLAG] {run} ...
+
+
+prog options
+============
+
+* **"--flag"** "FLAG" - a flag
+
+
+prog run
+========
+
+   prog run [--magic MAGIC]
+
+
+prog run options
+----------------
+
+* **"--magic"** "MAGIC" - magic
+"""
+    )
+
+
 @pytest.mark.sphinx(buildername="text", testroot="ref-duplicate-label")
 def test_ref_duplicate_label(build_outcome: tuple[str, str], warning: StringIO) -> None:
     assert build_outcome