Files
paperspec/docs/package/guides/check-and-build.md
T
alexmandClaude 03b4722023 docs: the tools' names in TitleCase
Prose names are PaperSpec, PaperDesk, PaperClaim and so on; commands, packages and paths stay lowercase.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014zNf4shD4zaCKLucZWPYL9
2026-10-21 09:49:58 -04:00

2.5 KiB

Check and rebuild the repository

Four commands work on a checkout of the PaperSpec repository, not on an installed package: check, build, stress and site. The checkout is the one an editable install points at, or else the one around the current folder.

Check everything

paperspec check

The checker validates every schema, record and package, confirms that every broken package is refused for the stated reason, recomputes every test vector, rebuilds everything and compares it byte for byte, loads every package into SQLite and back, and checks the prose, the links and the website. Each section prints how many checks it ran, and a passing run ends with All checks pass. The exit status is 0 when every check passed and 1 otherwise.

paperspec check --quick skips the byte-for-byte rebuild, the slowest part. The command does not run the Python code checks or the Markdown lint; pixi run check runs those first (Install).

Rebuild the vectors and fixtures

No expected value in the repository is typed by hand. The vectors and fixtures are computed from the hand-written sources in fixtures/src/ and the cases the builder defines in src/paperspec/cli/build.py. After you change a rule in the code, a fixture source or a case, rebuild and commit the regenerated files with the change:

paperspec build

paperspec build --out DIR builds elsewhere, so you can compare with diff -r DIR/vectors vectors before overwriting anything. The build is deterministic, and paperspec check proves it by rebuilding into a temporary folder and comparing every file.

Stress the oracle

paperspec stress --rounds 5

The vectors pin values; stress checks the invariants the chapters state, such as canonical JSON round trips and the zip reader never writing outside its folder, on random inputs from a seeded generator. A failure prints its seed, so paperspec stress --seed SEED reproduces it. The defaults are the seed 20261014 and 200 cases per property. Before a release, run it with the default seed and with one or two others.

Build the website

paperspec site --out /tmp/paperspec-site

The site mirrors the repository: each file is served at its own path, each Markdown file gets a rendered page beside it, and the schemas are at the addresses in their $id. It needs only the standard library. The pages you are reading are a separate site, built with Zensical by pixi run -e docs docs-build.