Skip to content

Checks

Jump to bottom
Alexander Refsum Jensenius edited this page Nov 6, 2026 · 3 revisions

Three checks run over the sources, and the last one runs the first two for you:

python scripts/tests/test_scripts.py   # tests for the helper scripts
python scripts/check-chapters.py       # chapter structure, citations, figures
./scripts/verify-book-build.sh         # full build with every notebook executed

Chapter checker

scripts/check-chapters.py reads the table of contents and checks every chapter for the template order (opening, prose, lab, critical look, summary, questions, further reading, apps), that every [@Key] citation exists in book/references.bib, and that every figure path resolves. Pass --book to point it at another book directory.

Style checker

scripts/check-style.py checks the prose against the course style guide: contractions, bold inside sentences, banned paragraph openers, sentences over forty words, em dashes in running prose, first-person singular, exclamation marks, the retired word "audiovisual", and the lecturer's "we" (reported for human judgement only).

python scripts/check-style.py                    # whole book, report only
python scripts/check-style.py --strict           # exit 1 on any hit except the "we" report
python scripts/check-style.py --files a.md b.ipynb

It exempts quoted and italic text, table cells, directive option lines and code blocks, and the idioms listed in scripts/style-allowlist.txt. Reading lists and tool lists separate an item from its description with a colon (- **Title**: description), as in the sibling book, so an em dash there is reported like any other. The style guide it enforces is the course folder's STYLE.md, which lives outside this repository. CI runs the checker in report-only mode.

Metrics

scripts/book_metrics.py prints words, reading time, sentence length, LIX, Flesch, citations, figures, exercises, apps, dropdowns, questions, and glossary coverage per chapter, and lists the glossary terms no chapter uses. With --core it measures only the main-flow prose, without dropdowns, exercises, summaries, question lists and reading boxes; every section should read at LIX 50 or below in that view. The script is a copy of the one in the Sensing Sound and Music repository, adapted to this book's chapter list.

python scripts/book_metrics.py --core

Workflows

  • Deploy Jupyter Book: runs both checkers, builds with executed notebooks, copies the apps, publishes to GitHub Pages.
  • Link check: exports the notebooks' Markdown cells and runs markdown-link-check over the pages, the notebooks, and the bibliography URLs. Can be started by hand from the Actions tab.
  • Accessibility check: runs pa11y over the built site and the apps. Can be started by hand.

Clone this wiki locally