[Docs] Every mixed colour written out, so no rule depends on color-mix()

.github/workflows/checks.yml

@@ -0,0 +1,70 @@
+name: Checks
+
+# Every push and every pull request. The deploy publishes whatever main holds,
+# so what main holds has to be checked before it lands, not after.
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  python:
+    name: Renderer
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: pip
+      - run: pip install -r requirements-dev.txt
+      - run: ruff check scripts hooks.py tests
+      # The renderer's own tests, including the golden pages: a change to what
+      # the Benchmarks section says shows up here as a diff to review.
+      - run: pytest
+      - run: shellcheck scripts/render_bench.sh
+
+  css:
+    name: Stylesheet
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # Two rules earn their keep here: a duplicated selector (the stylesheet
+      # once grew a 550-line copy of itself unnoticed, and the later copy won),
+      # and a disallowed `color-mix()` (an engine that cannot parse it drops the
+      # whole declaration, so a border disappears and an SVG fill paints black).
+      - run: npx --yes stylelint@16 "docs/assets/**/*.css"
+
+  site:
+    name: Site builds
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
+        with:
+          repository: tile-ai/TileOPs
+          path: TileOPs
+          fetch-depth: 1
+          sparse-checkout: |
+            docs/design
+            docs/perf
+            src/tileops
+            scripts/nightly_report.py
+          sparse-checkout-cone-mode: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: pip
+      - run: pip install -r requirements-docs.txt
+      # Every warning fails the job except one class: mkdocstrings reports one
+      # per parameter in TileOPs whose docstring carries no type, and the
+      # docstrings of another repository are not this repository's gate.
+      # `--strict` cannot make that distinction, so the log is read instead.
+      - name: Build the site, and fail on any warning of our own
+        run: |
+          set -o pipefail
+          mkdocs build 2>&1 | tee build.log
+          if grep -E '^WARNING' build.log | grep -v 'griffe:'; then
+            echo "::error::mkdocs reported the warnings above"
+            exit 1
+          fi

.github/workflows/deploy.yml

@@ -7,6 +7,12 @@ on:
 permissions:
   contents: write
 
+# Shared with the daily refresh: two `gh-deploy --force` runs at once would race
+# to publish gh-pages.
+concurrency:
+  group: gh-pages
+  cancel-in-progress: false
+
 jobs:
   deploy:
     runs-on: ubuntu-latest
@@ -26,7 +32,7 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: '3.12'
-      - run: pip install mkdocs-material "mkdocstrings[python]" mkdocs-include-markdown-plugin mkdocs-static-i18n jieba pyyaml black
+      - run: pip install -r requirements-docs.txt
       # Regenerate the Benchmarks page from the latest nightly snapshot so a
       # push deploy never serves a stale page. Falls back to the placeholder if
       # the snapshot is unavailable.

.github/workflows/render-benchmarks.yml

@@ -18,8 +18,11 @@ on:
 permissions:
   contents: write
 
+# Both this job and the push deploy publish gh-pages with `--force`, so the two
+# share one queue: a scheduled refresh and a merge landing together would
+# otherwise race, and the loser's pages would be the ones served.
 concurrency:
-  group: daily-refresh
+  group: gh-pages
   cancel-in-progress: false
 
 jobs:
@@ -44,7 +47,7 @@ jobs:
         with:
           python-version: '3.12'
 
-      - run: pip install mkdocs-material "mkdocstrings[python]" mkdocs-include-markdown-plugin mkdocs-static-i18n jieba pyyaml black
+      - run: pip install -r requirements-docs.txt
 
       - name: Render benchmark page from nightly-bench
         run: bash scripts/render_bench.sh

.gitignore

@@ -1,6 +1,9 @@
 site/
 __pycache__/
 .cache/
+.pytest_cache/
+.ruff_cache/
+tests/.golden-tmp/
 TileOPs
 docs/benchmarks/*.md
 !docs/benchmarks/index.md

.stylelintrc.json

@@ -0,0 +1,12 @@
+{
+  "rules": {
+    "no-duplicate-selectors": true,
+    "declaration-block-no-duplicate-properties": [
+      true,
+      { "ignore": ["consecutive-duplicates-with-different-values"] }
+    ],
+    "function-disallowed-list": ["color-mix"],
+    "no-invalid-double-slash-comments": true,
+    "block-no-empty": true
+  }
+}

CLAUDE.md

@@ -9,8 +9,7 @@ LLM operators across backends, built on TileLang. MkDocs + Material, deployed to
 ## Development
 
 ```bash
-pip install mkdocs-material "mkdocstrings[python]" mkdocs-include-markdown-plugin \
-  mkdocs-static-i18n jieba pyyaml black
+pip install -r requirements-docs.txt -r requirements-dev.txt
 git clone --depth 1 https://github.com/tile-ai/TileOPs.git TileOPs   # or symlink one
 mkdocs serve
 ```
@@ -22,6 +21,24 @@ and `design/` mirrors its `docs/design/`. Without it, mkdocstrings cannot import
 `mkdocs serve` serves under the `site_url` subpath, so the page is at
 `/TileOPs.github.io/`. `bash scripts/render_bench.sh` renders `docs/benchmarks/`.
 
+## Checks
+
+`.github/workflows/checks.yml` runs these on every push and pull request:
+
+| Command | Holds |
+|---------|-------|
+| `pytest` | The renderer, including `tests/golden/` — the pages a fixed snapshot must produce, byte for byte |
+| `ruff check scripts hooks.py tests` | `pyproject.toml`; `E501` off, the prose here is wrapped by hand |
+| `npx stylelint "docs/assets/**/*.css"` | No duplicate selector, no `color-mix()` — an engine that cannot parse a function drops the whole declaration, so a border vanishes and an SVG `fill` paints black |
+| `mkdocs build` | Fails on any warning of ours; griffe's are TileOPs' docstrings, not this repo's gate |
+
+Seven tests, and that is the intended size. `tests/fixtures/` is a trimmed
+snapshot — one testcase per path the renderer takes — and `tests/golden/` the
+three data pages it must produce. A change to what those pages say fails by
+design: read the diff, then `python tests/refresh_golden.py`. A unit test is
+added only for a rule the pages do not show; anything the golden pages already
+cover is not worth a second assertion on a docs site.
+
 ## Generated pages
 
 Never edit these by hand — change what produces them.