docs: color output for docs

.pre-commit-config.yaml

@@ -87,7 +87,8 @@ repos:
     - id: check-github-actions
     - id: check-github-workflows
     - id: check-gitlab-ci
-    - id: check-readthedocs
+    # Disabled due to schema issue for now:
+    # - id: check-readthedocs
     - id: check-travis
     - id: check-jsonschema
       name: Check projects

.readthedocs.yml

@@ -3,10 +3,10 @@
 version: 2
 
 build:
-  os: ubuntu-22.04
-  tools:
-    python: "3.12"
+  os: ubuntu-24.04
   commands:
+    - asdf install python 3.14-dev
+    - asdf global python 3.14-dev
     - asdf plugin add uv
     - asdf install uv latest
     - asdf global uv latest

docs/main.py

@@ -1,8 +1,12 @@
 import os
+import re
 import subprocess
 import sysconfig
 from typing import Any
 
+import rich.console
+import rich.text
+
 
 def define_env(env: Any) -> None:
     "Hook function for mkdocs-macros"
@@ -12,5 +16,15 @@ def subprocess_run(*args: str) -> str:
         "Run a subprocess and return the stdout"
         env = os.environ.copy()
         scripts = sysconfig.get_path("scripts")
+        env.pop("NO_COLOR", None)
         env["PATH"] = f"{scripts}{os.pathsep}{env.get('PATH', '')}"
-        return subprocess.run(args, check=True, capture_output=True, text=True, env=env).stdout
+        env["PYTHON_COLORS"] = "1"
+        output = subprocess.run(args, check=True, capture_output=True, text=True, env=env).stdout
+        rich_text = rich.text.Text.from_ansi(output)
+        console = rich.console.Console(record=True, force_terminal=True)
+        console.print(rich_text)
+        page = console.export_html(inline_styles=True)
+        result = re.search(r"<body.*?>(.*?)</body>", page, re.DOTALL | re.IGNORECASE)
+        assert result
+        txt = result.group(1).strip()
+        return txt.replace("code ", 'code class="nohighlight" ')

docs/options.md

@@ -1714,9 +1714,7 @@ Platform-specific environment variables are also available:<br/>
 
 ### Options
 
-```text
 « subprocess_run("cibuildwheel", "--help") »
-```
 
 ### Return codes
 

noxfile.py

@@ -173,7 +173,7 @@ def bump_version(session: nox.Session) -> None:
     session.install_and_run_script("bin/bump_version.py")
 
 
-@nox.session(default=False, python="3.12")
+@nox.session(default=False)
 def docs(session: nox.Session) -> None:
     """
     Build the docs. Will serve unless --non-interactive

pyproject.toml

@@ -76,6 +76,7 @@ docs = [
     "mkdocs-macros-plugin",
     "mkdocs==1.6.1",
     "pymdown-extensions",
+    "rich",
 ]
 test = [
     "build",