docs: wire check:examples into CI, derive the status badge, consolidate the IA - #26
Merged
Conversation
docs-site/package.json has shipped a check:examples gate -- it cargo-checks every documented Rust example against the real crate -- but nothing ran it, so a documented example could stop compiling without CI noticing. The gate invokes cargo, so docs-checks now installs a Rust toolchain alongside bun and carries the same CARGO_TERM_COLOR / PYO3_USE_ABI3_FORWARD_COMPATIBILITY env that lint-test does. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VcwF3j7E2HxMc3Fnq4fmu7
The status pill was injected through each page's `banner.content`, because the branch that added it could not touch astro.config.mjs. That put the badge BESIDE the `status` field instead of deriving it FROM it, and needed a rule in check-content-schema.mjs to stop the two disagreeing. Now a Starlight `Banner` override (src/components/DocStatusBanner.astro, registered under `components:`) reads `status` off the page and renders the pill itself. The badge markup is gone from all 59 pages and from the generator; the badge-consistency rule is retired -- there is nothing left to drift. A page may still set `banner.content` of its own (index.md keeps its Quickstart CTA); it then replaces the default sentence beside the pill. The markup is the same `.sl-banner` element Starlight emits, so the existing `doc-status--generated|draft|reviewed` palette in starlight.css applies unchanged in light and dark. Two fixes the change forced out of the freshness gate, which is what makes the stamps mean anything: - It treated any file change as a content change, so removing a banner line from frontmatter marked ten human-reviewed pages stale -- offering a choice between a false re-review and a status downgrade. It now falls back to the last commit whose *body* differs, ignoring frontmatter-only edits; an uncommitted body edit or unreadable history still fails strictly. - mtimes were read in UTC while commit dates were read as local civil days, so every stamp made after 17:00 Pacific looked like it predated its own page. mtimes are now local days too. check:examples 0 · astro build 0 (59 pages carry a pill) · check-links 0 · check-content-schema 0 (59 files: 40 generated, 8 draft, 11 reviewed) · api-drift 0. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VcwF3j7E2HxMc3Fnq4fmu7
The same 39 modules were indexed four times under three taxonomies that disagreed with each other, and the sidebar had 20 top-level groups, five of them holding a single page. Sidebar: 20 top-level groups -> 7 (Getting Started, Setup, Workflows, Modules, Reference, Governance, Coverage). The 13 AFML chapter groups are nested one level inside Modules and start collapsed, so a one-page chapter costs a line instead of a heading; the four single-page chapter groups are paired into 'Ch 5-7: Features & Validation' and 'Ch 8-9: Importance & Tuning'. No module page left the sidebar. modules/index.md is now the single canonical index, and says so. It grew a 'By language surface' section generated from moduleDocs.ts. Deleted, with where each page went: - module-reference/api-surfaces.md — a hand-maintained fourth index of the same modules. Its Rust list and Python namespace lists are now generated into modules/index.md from `apiSurface` and `pythonApis`, so they cannot drift again; the generated version is also fuller than the page was (31 namespaces against 12). Three links in the two workflow pages and the '/api-reference' redirect now point at /modules/. - module-reference/indexing-and-discovery.md — prose describing the sidebar, sitting in the sidebar. Its three discovery paths and its search advice fold into the home page's Recommended Reading Path. The '/search' redirect now points at the home page. by-afml-chapter.md stays: it is the one taxonomy with editorial value. The generator now refuses two python modules claiming one namespace, since the index can only link a namespace to one page. astro build 0 (97 pages) · check-links 0 (109 files, redirects included) · check-content-schema 0 (57 files) · check:examples 0 · api-drift 0. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VcwF3j7E2HxMc3Fnq4fmu7
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
1 participant
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.
Three cleanups that were blocked until the docs stack merged. Grouped because all three touch
docs-site/astro.config.mjs.1 —
check:examplesruns in CI (756ef30)The gate that compiles every documented Rust example existed but nothing ran it. Added to the
docs-checksjob, with a Rust toolchain step since it invokes cargo.This matters: that gate already caught a real regression on
main(theget_parkinson_volrenameleft the docs referencing a dead symbol). Until now it only caught it because someone ran it by hand.
2 — The status badge is derived, not duplicated (
47e1035)The badge was injected through each page's frontmatter
banner.content, because the branch thatintroduced it could not touch
astro.config.mjs. So the badge sat beside thestatusfieldrather than being derived from it, and
check-content-schema.mjscarried an extra rule to failwhen the two disagreed.
Now a Starlight
Bannercomponent override readsstatusfrom frontmatter directly. The badgemarkup is gone from all 57 pages, removed from the generator, and the consistency rule is retired —
the two can no longer drift because there is only one source.
3 — Information architecture (
5b2a746)The same 39 modules were indexed four times under three contradicting taxonomies, with a
20-group sidebar, five groups holding a single page.
Reference, Governance, Coverage — with AFML chapters nested inside Modules rather than at top level
modules/index.mdis now the single canonical module indexmodule-reference/api-surfaces.mdmerged into it as By language surface, then deletedmodule-reference/indexing-and-discovery.md— prose describing the sidebar — deleted, itsdiscovery paths folded into the reading path
by-afml-chapter.mdkept; the audit judged it the best page on the siteBoth deleted pages were redirect targets, which is precisely the bug class that broke this site
before. Repointed:
/api-reference→/openquant/modules/,/search→/openquant/. Verified bothresolve to files that exist.
Verification
astro build0 (97 pages) ·check-links0 (109 files, redirects included) ·check-content-schema0 (57 docs: 40 generated, 6 draft, 11 reviewed) ·check:examples0(39 examples) ·
check:api-drift0 · generator idempotent.Badge renders on 57 of 57 doc pages.
check-linkspassing after the deletions is theload-bearing check — it is what proves no dangling link or redirect was left behind.