Add the Zensical documentation of the Python package (docs/package, built by the docs workflow), merge the standard publish workflow with the setuptools-scm tag check, add the SPDX header rule to ruff, restructure the README, and point every repository and registry address at the Gitea organization papers. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B8cL4zN4XpaQF5cBtASzfq
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.