Publish the package and its documentation, and move to the papers organization
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
This commit is contained in:
37 files changed
+1005
-83
No files matched your search
@@ -0,0 +1,51 @@
|
||||
# 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
|
||||
|
||||
```sh
|
||||
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](../start/install.md#the-pixi-tasks)).
|
||||
|
||||
## 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:
|
||||
|
||||
```sh
|
||||
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
|
||||
|
||||
```sh
|
||||
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
|
||||
|
||||
```sh
|
||||
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`.
|
||||
Reference in new issue
Block a user