Documentation¶

The site is built with Zensical from docs/site/ and zensical.toml. The Python API reference is generated by mkdocstrings from the package's docstrings and the compiled module's stub (python/mibz2/_mibz2.pyi).

just docs-serve   # build, serve and rebuild on change
just docs-check   # strict build, site checks, and the pages' examples as tests

docs/scripts/check_site.py checks that every page is in the nav, that internal links and anchors resolve, that every page has a description matching its llms.txt entry, and that every public name is in the API reference.
docs/conftest.py runs each page's Python examples with pytest (pytest docs/site); a pycon block's output must match.
docs/scripts/bench_history.py turns the bench-results branch into the benchmark pages' data (docs/site/assets/bench-history.json) and tables (docs/generated/) before each build. Without a checkout of the branch (--store), it reads origin/bench-results, or writes empty ones.
docs/site/assets/data/lane-sweeps.json holds the measured walk timings by lane count that Why 32 couriers beat one draws (assets/javascripts/couriers.js). It is written by hand, from the record: one panel a sweep, each with its own axes, its points (x, y, and optionally lo and hi for an interval) and its source. A new sweep is a new panel; the page draws every panel. Only measured points go in it.

Publishing¶

.github/workflows/site.yml builds the site on every push to master, and after each Benchmark run on master, and publishes it to the gh-pages branch, served at https://lmmx.github.io/mibz2/. A pull request from this repository gets a preview under pr-preview/pr-<number>/, linked from a comment on the pull request and removed when it closes. Previews start once the repository's Pages source is set to the gh-pages branch.