[Docs] Prepare the site for TileOPs' first PyPI release

README.md

@@ -50,6 +50,26 @@ Three groups of pages are not written by hand:
 the repo-relative paths mirrored content arrives with, and expands the single
 Benchmarks nav entry, since those pages do not exist until the renderer has run.
 
+## Checks
+
+CI (`.github/workflows/checks.yml`) runs these on every push and pull request:
+
+```bash
+pip install -r requirements-dev.txt
+ruff check scripts hooks.py tests
+pytest -rs                              # the renderer, and tests/golden/ byte for byte
+python scripts/check_api_pages.py       # every op the API pages name is exported
+npx stylelint "docs/assets/**/*.css"
+bash scripts/dev.sh build               # mkdocs build; any warning not from griffe fails
+```
+
+`tests/golden/` holds the Benchmarks pages the trimmed snapshot in `tests/fixtures/`
+must produce. After an intended change to what they say, review the diff, then run
+`python tests/refresh_golden.py`.
+
+Which ops a `docs/api/` page names is written by hand. When TileOPs adds or removes
+an op, `scripts/check_api_pages.py` reports it.
+
 ## Bilingual pages
 
 English lives at the site root, Chinese under `/zh/`. A Chinese page is a
@@ -59,3 +79,7 @@ a page's two versions are kept in step by hand.
 
 A page with no translation falls back to English at the same URL, with a notice
 prepended by `hooks.py` — so the Chinese nav is never sparse.
+
+A figure with text has one SVG per language, `img/<name>.svg` and `img/<name>.zh.svg`.
+The user-guide figures are drawn from sources under `figures/user-guide/`: edit the
+source, then run `figures/user-guide/render.sh`.

docs/api/elementwise.md

@@ -283,12 +283,6 @@ what runs when you call `op(...)`.
       heading_level: 3
       members: ["__init__", "forward"]
 
-::: tileops.elementwise.GELUTanhAndMulFwdOp
-    options:
-      show_root_heading: true
-      heading_level: 3
-      members: ["__init__", "forward"]
-
 ## Comparison
 
 ::: tileops.elementwise.EqFwdOp

docs/api/index.md

@@ -44,8 +44,8 @@ a tool rather than an op, comes last. The Benchmarks pages use the same order.
 Two things this reference does not carry:
 
 - **What each op is allowed to receive.** The authoritative dtype domains, shape rules
-  and measured workloads are in the op's spec; see [Writing a
-  Spec](../user-guide/manifest/index.md).
+  and measured workloads are in the op's spec; see [Reading and
+  Writing Specs](../user-guide/manifest/index.md).
 - **How fast it is.** Device time against the fastest alternative on each workload is on
   the [Benchmarks](../benchmarks/index.md) pages.
 

docs/backends.md

@@ -37,7 +37,8 @@ A package outside TileOPs takes over every call of an op through a target. A tar
 follows the op's manifest signature, and the backend writes a `build_kernel` for it. The
 kernel interfaces and call specs of TileOPs' ops are not public API, so a backend does not
 add an implementation to a single kernel interface; see
-[How a backend joins TileOPs](user-guide/dispatch/backends.md).
+[How a backend joins TileOPs](user-guide/dispatch/backends.md). The public modules a
+backend imports are listed on [API Stability](stability.md).
 
 ## Four things to write
 
@@ -636,7 +637,7 @@ OpNotAvailableError: RMSNormFwdOp's in-tree kernels do not run on cpu; known tar
 tensors; this error shows the outcome that the no-fall-back rule avoids.
 
 **When a backend package fails to import**, TileOPs skips it, issues a warning, and
-collects the reason into `load_failures()`. One broken plugin does not make TileOPs fail
+collects the reason into `load_failures()`. One broken backend package does not make TileOPs fail
 to import. If registration raises part way through, everything that backend registered in
 that pass is **rolled back**, and no partly registered target is left in the registry.
 
@@ -786,8 +787,8 @@ How the op layer looks up that table, and what it does on a miss, is in
 
 Two consequences:
 
-- **An entry may not last.** When a call fails, the op revokes its target decision and
-  drops its memo table. A backend must not assume the callable it returned stays alive;
+- **An entry may not last.** When the call that selected the target fails, the op revokes
+  that choice and drops its memo table. A backend must not assume the callable it returned stays alive;
   the callable holds its own references to the resources it depends on.
 - **A finer or a coarser grain is handled on the backend side.** Finer distinctions are
   made inside the backend; to rebuild less often, the backend adds a cache inside