9.7: the book — PythonTap's documentation as an mdBook, published to Pages

[tap]

Plan item 9.7 (docs/TAP-PYTHON-PLAN.md, Phase 9 of docs/PRODUCTION-PLAN.md): the book, after 2.0.0.

Merging this publishes a public website. book-pages.yml deploys the book to GitHub Pages on every push to main that touches it, at https://tap.github.io/PythonTap/ (which redirects to the custom domain, like SampleRateTap's book). Pages isn't enabled on this repo yet, so the first deploy will fail until it is: Settings → Pages → Source: GitHub Actions. After that, re-run the workflow or use Run workflow.

What it is

An mdBook under book/, in the family's shape (SampleRateTap's). The ReadMe's sections become its chapters:

• Using it: installing, writing a class, audio (tap.python~), worker mode, objects without audio (tap.python), performance, errors and limits.
• Examples: every python/*.py, and allpass-doc.ipynb rendered.
• Contributing: building, testing, and the design (D1–D11, the layers, the rules).
• The CHANGELOG.

Nothing that ships is copied into the book, so nothing can drift:

• The examples and the CHANGELOG come in through {{#include}}.
• scripts/notebook-to-book.py renders the notebook page at build time from the notebook as committed (executed). It uses only the standard library, and its output is gitignored.
• The performance tables now have one home, book/src/performance.md, which scripts/update-perf-docs.py writes. They were moved, not regenerated: they are still Sep 30's, as decided in 9.6.

The ReadMe is the front door

It's down from 250 lines to 66: what it is, install, a quick start (a four-step mygain.py), and links to the book. Everything that sent readers to the ReadMe for a rule or a measurement now points to the book: the guide, tutorial 3, the tap.python~ help (its numpy-tab comment is now shorter than before, so it still fits its box), the hand-written reference page, and code comments. The vignette stays the short form, written separately, as decided on 2026-10-09.

CI

• build.yml → book: renders the notebook, builds with mdBook 0.4.40 (pinned by SHA256, as in SampleRateTap) with warnings as errors, and uploads the site as the book artifact so it can be looked at before merging.

• book-pages.yml (new): the same build, deployed to Pages from main. It is the one workflow with pages: write and id-token: write. The configure-pages/upload-pages-artifact/deploy-pages pins are SampleRateTap's, checked against their tags (v5.0.0, v3.0.1, v4.0.5).

• scripts/check-docs.py (already run by the linux-max-glue release row) now checks the book and the ReadMe as well, since mdBook checks none of this:

  • every chapter is listed in SUMMARY.md;
  • every {{#include}} names a file;
  • every relative link resolves, anchors included.

  I tested it with a broken link, a missing anchor, a bad include and an orphan chapter, and it caught all four.

• Favicons: book/theme/favicon.{svg,png} are TapHouse v7 copies (sync.sh --icon PythonTap). The drift check already guards them now that book/book.toml exists.

Checked locally

• mdBook 0.4.40 builds with no warnings, and I looked at the pages in a browser.
• check-docs.py is clean.
• Core battery 112/112, glue test 1/1, clang-format clean on the one C++ change, a comment.

🤖 Generated with Claude Code

https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz