Fix for docs not building (#1146)

audreyfeldroy · web-flow · commit 1de4271790f1 · 2026-07-27T12:58:33.000+08:00
## What Pygments 2.20.0 has a breaking change that prevents Air's documentation from building. This PR excludes only that release with `pygments>=2.19.2,!=2.20.0`; the lockfile stays on working version 2.19.2 until a newer fixed release is available. Reference: pygments/pygments#3076 This PR also fixes the misspelled `air.forms` documentation reference and adds an integration test that builds the complete documentation site with MkDocs. ## Reviewer Focus The constraint excludes the known-bad 2.20.0 release while automatically permitting 2.20.1 or later once published, so no follow-up constraint change is required. ## Checklist - [X] Diff contains only changes for this task — no unrelated refactoring or cleanup - [ ] Addresses exactly one issue or feature - [X] New or changed behavior has test coverage - [X] This is the simplest viable approach - [X] AI provenance section removed or accurate
diff --git a/docs/api/forms.md b/docs/api/forms.md
@@ -1,3 +1,3 @@
 # Forms
 
-::: air.forms
+::: air.form
diff --git a/pyproject.toml b/pyproject.toml
@@ -88,7 +88,7 @@ dependencies = [
     "lxml>=6.0.2", # https://pypi.org/project/lxml
     "minify-html>=0.18.1", # https://pypi.org/project/minify-html
     "nh3>=0.3.2", # https://pypi.org/project/nh3
-    "pygments>=2.19.2", # https://pypi.org/project/pygments
+    "pygments>=2.19.2,!=2.20.0", # https://pypi.org/project/pygments
     "python-multipart>=0.0.22", # https://pypi.org/project/python-multipart
     "rich>=14.3.2", # https://pypi.org/project/rich
     "selectolax>=0.4.6", # https://pypi.org/project/selectolax
diff --git a/tests/test_docs.py b/tests/test_docs.py
@@ -0,0 +1,27 @@
+"""Documentation integration tests."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_documentation_builds(tmp_path: Path) -> None:
+    subprocess.run(
+        [
+            sys.executable,
+            "-X",
+            "utf8",
+            "-m",
+            "mkdocs",
+            "build",
+            "--strict",
+            "--site-dir",
+            str(tmp_path),
+        ],
+        cwd=PROJECT_ROOT,
+        check=True,
+    )
diff --git a/uv.lock b/uv.lock

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`	`1`	`# Forms`
`2`	`2`
`3`		`-::: air.forms`
	`3`	`+::: air.form`