[Docs] Every mixed colour written out, so no rule depends on color-mix() - #38
Merged
Conversation
A declaration an engine cannot parse is dropped whole, and `color-mix()` is not resolved by every browser a reader arrives with. What that costs is not a slightly wrong colour: the rule that draws the group's teal edge loses its border, the hairline after a workload's code disappears, the middot between entries loses its ink, and an SVG `fill` falls back to SVG's own default, black — which is what painted the roofline's shaded region as a black wedge. All 45 mixes are replaced by the colour they evaluate to, computed in sRGB against the palette they referenced: `color-mix(in srgb, var(--tf-teal), transparent 55%)` is `rgba(22, 112, 107, 0.45)`. `--tf-rule` is now a literal too, so the variables carry values rather than expressions. Nothing changes where color-mix was already supported; everywhere else the page arrives as designed.
Nothing checked this repository. A 1200-line renderer decides what every
benchmark number on the site says, and the only way a regression was found was
by looking at the published page — which is how a 550-line duplicated block of
CSS and a `color-mix()` that silently dropped whole declarations both shipped.
Checks, on every push and pull request:
* `pytest` — 35 tests. `tests/fixtures/` is a trimmed snapshot carrying one
testcase per path the renderer takes, and a manifest fragment declaring one
op per resolution path. `tests/golden/` holds the pages that snapshot must
produce, byte for byte, so a change to what the pages say arrives as a diff
to read rather than as a surprise on the site. `tests/refresh_golden.py`
rewrites them once the diff has been read.
* `ruff check` — E,F,W,I,B,UP, with E501 off: the prose in these files is
wrapped by hand.
* `stylelint` — no duplicate selector, no `color-mix()`. Both rules are the
two CSS failures above, stated as rules.
* `mkdocs build --strict` and `shellcheck`.
Two bugs the first tests found:
* `_bind()` bound one symbol to two values inside a single tensor: `[D, D]`
against `[64, 32]` rendered as `[D, D]` with `D=32`, which is false. The
template is now rejected and the row prints its concrete shape.
* `family_of()` classified by a substring before the package: `linear` matches
`linear_attention`, so every linear-attention op whose name lacked another
keyword was published on the GEMM page. The package decides now, and every
directory under `tileops/ops/` is mapped.
Supporting changes: the 11 duplicate selectors stylelint reports are merged (no
property conflicted, so what the browser computed does not change); `zip()` is
strict where the two sequences are built from one list; the workflows install
from `requirements-docs.txt` rather than an inline list that had grown a `black`
nobody runs; and both deploys share a `gh-pages` concurrency group, since two
`gh-deploy --force` runs at once race to publish.
… build judged on our own warnings The first run failed on two things that were about the checks, not the code. The golden pages were rendered on a machine with a TileOPs checkout beside them, so `reading.md` quoted the roofline tool's own at-ceiling wording, while CI has no checkout and rendered the degraded one. `load_sol_engine` now takes the checkout to import from, and the tests point it at a directory holding nothing: the pages under test depend on this repository alone, and a contributor with a checkout renders exactly what CI renders. `mkdocs build --strict` failed on 22 warnings, every one of them mkdocstrings reporting a parameter in TileOPs whose docstring carries no type. The quality of another repository's docstrings is not this repository's gate, and `--strict` cannot tell the two apart, so the job reads the log: any warning that is not griffe's fails it.
… that test The workload key for an op the manifest does not declare emitted `<li>` directly under a `<div>` — no list, so none of the key's styling applied to the 34 ops in that state. Wrapped like every other group. Three tests were weaker than they read. The unknown-tag test asserted over a fixture that held no unknown tag, so it would have passed with the reporting deleted; the fixture now carries `brand-new-lib` and the end-to-end test asserts the run says so. The template-evaluation path was never reached — `ChunkScanFwdOp` names its scalars `batch`/`num_chunks` while its templates say `B`/`S`, so the shapes resolved to nothing — and a new `TemplatedFwdOp` covers both that path and a tensor in a dtype of its own (`mask`, `bool`). `tests/golden/reading.md` is dropped: that page is prose written in the renderer with nothing read out of the snapshot, so holding it byte for byte only means refreshing a golden file whenever a sentence is edited, and the sentence is already in the diff. One assertion checks the page is written. Also: `black` is back in requirements-docs.txt (mkdocstrings warns on every build without it, and the site job fails on warnings of ours); ruff's line length is 100; the comment on `_MODULE_FAMILY` says which packages are meant to fall through to the keywords; the Checks section of CLAUDE.md is cut to a table.
… not show This is a documentation site. The golden pages are worth holding — one fixed snapshot in, three committed pages out, and every rule in the renderer is a rule about what they say. Most of the rest restated the implementation: that `bfloat16` abbreviates to `bf16`, that a shape formats with brackets, that XML properties parse into the dict they parse into. All of it is already visible in the golden pages, and none of it would fail for a reason worth a maintainer's morning. What is left: the three pages byte for byte, two renders compared so an ordering that depends on dict iteration cannot reach the site, the run's own report of what it could not describe, a render with no manifest at all, and three rules the pages do not show — a template may not bind one symbol to two values, a template is parsed rather than executed, and the package decides where an op is published. Both were bugs found by the first version of this suite; the third is why the evaluator has a whitelist. 38 tests to 7, three test files to one.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problems
color-mix()is not resolved by every browser a reader arrives with, and a declaration an engine cannot parse is dropped whole.fillthat is dropped falls back to SVG's own default, black. That is what painted the roofline figure's shaded region as a black wedge over the grid.Changes
color-mix(in srgb, var(--tf-teal), transparent 55%)becomesrgba(22, 112, 107, 0.45).--tf-ruleis a literal too, so the palette variables carry values rather than expressions.Nothing changes where
color-mix()was already supported.mkdocs buildclean; the built stylesheet contains nocolor-mix(outside that note.