docs: make the coverage dashboard recompute itself - #30
Merged
Conversation
coverage.md opens by promising that every number on it ships with the command that produced it, and then closes by admitting the numbers were hand-transcribed from commands someone ran once. That gap had already opened: the page claimed 59 docs pages (8 draft) when the tree had 57 (6 draft), and 12 enriched / 27 stub module pages when the real split was 10 full-template / 29 base — moduleDocs.ts was rewritten after the page was last touched. It also said check:api-drift was failing; it passes. So this adds the command. scripts/docs/check_coverage.py derives all three tables from the tree and compares them with marked regions of the page, failing on drift; --write regenerates them. Prose outside the markers is untouched, so the page stays hand-written where it should be. Undocumented public modules are now a hard failure rather than a line in a table. docs-site/coverage_allowlist.toml is the only place a gap may live, and an entry costs a reason and an expiry date, so a gap cannot be parked there indefinitely. data_processing and bars are the two current entries. An exemption for a module that turns out to be documented also fails, because a stale exemption is how an allowlist stops meaning anything. Wired into check:docs and the docs-checks CI job next to the other docs gates. Python only — the job already runs check:api-drift on the runner's bare python3 before its setup-python step. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EfGwkvxHYD4UbTQEU4Mx2S
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.
The coverage page told you to trust it because "every number comes with the command that produced it" — but nothing ran those commands. It was already stale: it claimed 59 pages / 8 draft when the real tally was 57 / 5, and it stated
check:api-driftwas "currently failing" when that gate exits 0. It was overtaken about an hour after it was written.This makes the page regenerate itself and adds
check:coverageto the docs gates.<!-- coverage:begin:NAME -->regions are derived from source — frontmatterstatusacross the Starlight collection,pub modinlib.rs, andpython/openquant/*.py. Prose outside the regions is untouched.--checkfails on drift,--writeregenerates.coverage_allowlist.tomlcarries a reason and an unexpired date. An exemption for a module that is documented also fails — a stale exemption is how an allowlist stops meaning anything.utilis treated as a namespace rather than a gap, sinceutil::fast_ewmaandutil::volatilityhave their own pages.Verified independently of the author. Clean run of every gate exits 0 (build 97 pages, links 109 files, api-drift, content-schema, coverage, 39 Rust examples). Negative-tested: an undocumented
pub mod→ exit 1 naming it; a perturbed tally number → exit 1coverage.md is stale in: status-tally; a date-only edit → exit 0 by design. All restored, clean run 0.Origin: salvage of an abandoned February effort. Two other candidate features from it were rejected as superseded — the chapter IA (its mapping was a strict subset of
by-afml-chapter.mdand mapped ch6 to the wrong modules) and a hand-maintainedapiCatalog.ts(apiInventory.tsis generated and gated).