Skip to content

docs: a Docs tab, light code boxes, and an illustrated How it works page - #24

Merged
Paururo merged 2 commits into
mainfrom
docs/docs-tab
Oct 17, 2026
Merged

Paururo merged 2 commits into
mainfrom
docs/docs-tab

Conversation

@Paururo

@Paururo Paururo commented Oct 17, 2026

Copy link
Copy Markdown
Member

What changes

  • Docs tab. Every long page now lives in the site's design: a page list, contents that follow the reading, previous and next links, a search box over all pages (press /) and an edit link to GitHub. tools/build_docs.py builds the pages from the markdown, which stays the source and still reads on GitHub.
  • Code boxes follow the theme. In the light theme they are light instead of black.
  • How it works. A new page follows one empty cell through seven animated drawings: the matrix says absent, the gene's sequence, the search, what the hit is, the neighbours, the policy, and what gets written down. The reader picks what the search finds (seven cases), whether the neighbours agree and the policy, and the drawings and the decision change with them. It works with reduced motion, on phones and in both themes.
  • Every page has the same header, with How it works in it.

Checks

tools/check_site.py now also:

  • fails if a documentation page no longer matches its markdown (fix: python3 tools/build_docs.py);
  • checks links and anchors on every documentation page;
  • holds the walkthrough to src/pipeline.rs: its policy table must equal matrix_policy_corrects, every state must be one evidence_state writes, every rescue_type a form RescueType prints, every matrix action one matrix_action writes, and every column one of ORTHOLOGY_EVIDENCE_COLUMNS.

Each new check was broken on purpose and failed as it should. Locally fmt, clippy, the tests, the build, check_site.py --run-tutorial and the auto-merge gate check all pass, and every page fits at 360 and 390 px with no sideways scroll.

… light theme

Every long page becomes a page of the website, with the site's header and theme, a page list, contents that follow the reading, previous and next links, a search box over all of them and an edit link to GitHub. tools/build_docs.py writes them from the markdown, which stays the source and still reads on GitHub, and tools/check_site.py now fails when a page no longer matches its markdown or any page of the site has a dead link. Code boxes are light in the light theme, and one-line commands wrap instead of running under the copy button.
… decision

Seven animated drawings follow one empty cell from the matrix through the search, what the hit is, the neighbours and the matrix policy to what gets written down, and the reader picks what the search finds, whether the neighbours agree and the policy. The drawings decide with a copy of evidence_state and matrix_policy_corrects, and check_site.py now fails if the policy table, a state, a rescue type, a matrix action or a column drifts from the code. Every page gets the same header, with the new page in it.
@Paururo Paururo added documentation Improvements or additions to documentation ci Workflows, automation config, and the tools/ scripts labels Oct 17, 2026
@Paururo
Paururo merged commit 89a23d3 into main Oct 17, 2026
7 checks passed
@Paururo
Paururo deleted the docs/docs-tab branch October 18, 2026 08:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci Workflows, automation config, and the tools/ scripts documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant