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,9 @@
|
||||
# Get started
|
||||
|
||||
Two pages take you from nothing to a result.
|
||||
|
||||
1. [Install](install.md) the package from the studio's package registry, or work from a checkout.
|
||||
2. [Quick start](quick-start.md) validates the example paper and loads it into a database.
|
||||
|
||||
The package needs Python 3.14.
|
||||
It is the only version with the Unicode 16.0 character data the specification pins, and the package refuses to import on any other.
|
||||
@@ -0,0 +1,74 @@
|
||||
# Install
|
||||
|
||||
The package needs Python 3.14.
|
||||
Its base install has no dependencies: every module imports with the standard library alone.
|
||||
Three extras add what some modules need:
|
||||
|
||||
| Extra | Adds | Needed by |
|
||||
| --- | --- | --- |
|
||||
| `schema` | `jsonschema`, `referencing` | schema validation, so `package.validate` and `corrections.gate` |
|
||||
| `crypto` | `cryptography` | Ed25519 signatures and HKDF in `crypto`, which the signature and receipt checks use |
|
||||
| `tools` | both of the above | the `paperspec` command, and any program that validates packages |
|
||||
|
||||
## From the studio's package registry
|
||||
|
||||
The registry does not mirror PyPI, so an installer needs two indexes: the registry for `paperspec`, and PyPI for `jsonschema`, `referencing` and `cryptography`.
|
||||
Tie `paperspec` to the registry wherever the installer allows it, so that a package of the same name on PyPI is never chosen instead.
|
||||
`[CHECK: no version tag has been pushed yet, so the registry holds no release until the first tag is published]`
|
||||
|
||||
With pixi, in `pixi.toml`:
|
||||
|
||||
```toml
|
||||
[pypi-dependencies]
|
||||
paperspec = { version = ">=0.1.1", extras = ["tools"], index = "https://git.scient.ing/api/packages/papers/pypi/simple" }
|
||||
```
|
||||
|
||||
With uv, in `pyproject.toml`:
|
||||
|
||||
```toml
|
||||
[[tool.uv.index]]
|
||||
name = "scienting"
|
||||
url = "https://git.scient.ing/api/packages/papers/pypi/simple"
|
||||
explicit = true
|
||||
|
||||
[tool.uv.sources]
|
||||
paperspec = { index = "scienting" }
|
||||
```
|
||||
|
||||
With pip, which cannot tie a package to an index and takes the highest version from either:
|
||||
|
||||
```sh
|
||||
pip install --index-url https://git.scient.ing/api/packages/papers/pypi/simple/ --extra-index-url https://pypi.org/simple/ "paperspec[tools]"
|
||||
```
|
||||
|
||||
If the organization or the package is private, the installer also needs a token with the `read:package` scope, for example in a `~/.netrc` entry for `git.scient.ing`.
|
||||
|
||||
## From a checkout
|
||||
|
||||
Clone the repository and let pixi set up a pinned environment, with the package installed editable:
|
||||
|
||||
```sh
|
||||
git clone https://git.scient.ing/papers/paperspec
|
||||
pixi install
|
||||
pixi run check
|
||||
```
|
||||
|
||||
`pixi run check` runs the formatter, the linter, the type checker, the Markdown lint, the tests and the repository's own checker, and ends with `All checks pass.`
|
||||
Without pixi, install the checkout with `pip install -e ".[tools]" --group dev` on Python 3.14.
|
||||
|
||||
## The pixi tasks
|
||||
|
||||
| Task | Does |
|
||||
| --- | --- |
|
||||
| `check` | Every check CI runs, in order: `fmt-check`, `lint`, `typecheck`, `lint-md`, `test`, `verify`. |
|
||||
| `verify` | `paperspec check`, the repository's own checker. |
|
||||
| `quick` | `paperspec check --quick`, which skips the byte-for-byte rebuild. |
|
||||
| `fmt`, `fmt-check` | Format the code with ruff, or check the formatting. |
|
||||
| `lint`, `lint-fix` | Lint with ruff, or lint and apply the safe fixes. |
|
||||
| `typecheck` | Type-check `src/` with ty. |
|
||||
| `test`, `cov` | Run the pytest suite, or run it with branch coverage that fails under 90%. |
|
||||
| `lint-md` | Lint every Markdown file with markdownlint. |
|
||||
| `build`, `load`, `validate`, `stress`, `site` | The commands of the same names. |
|
||||
| `hooks` | Install the git pre-commit hooks. |
|
||||
| `docs-build`, `docs-serve` | Build these pages strictly into `build/docs`, or preview them. |
|
||||
| `dist` | Build the sdist and wheel into `dist/`. |
|
||||
@@ -0,0 +1,59 @@
|
||||
# Quick start
|
||||
|
||||
This page validates the repository's example paper, shows what a refusal looks like, and loads the paper into a database.
|
||||
Run every command from the root of a checkout (see [Install](install.md)); the example is a synthetic chemistry paper in `fixtures/packages/hale2026harmonic-damb`.
|
||||
|
||||
## Validate a package
|
||||
|
||||
```sh
|
||||
paperspec validate fixtures/packages/hale2026harmonic-damb
|
||||
```
|
||||
|
||||
```text
|
||||
fixtures/packages/hale2026harmonic-damb: valid
|
||||
```
|
||||
|
||||
The exit status is 0.
|
||||
A broken package prints one line per failure, as `package: where: rule: message`, and exits with status 1.
|
||||
The folder `fixtures/invalid/` holds packages that each break one named rule:
|
||||
|
||||
```sh
|
||||
paperspec validate fixtures/invalid/text-edited/package
|
||||
```
|
||||
|
||||
```text
|
||||
fixtures/invalid/text-edited/package: s0fn2fj: doc.hash.text-hash: text_hash does not recompute
|
||||
fixtures/invalid/text-edited/package: s0fn2fj: doc.hash.match-hash: match_hash does not recompute
|
||||
…
|
||||
```
|
||||
|
||||
Each rule ID, such as `doc.hash.text-hash`, is listed in <https://paperspec.scient.ing/registry/rules.json> with the chapter of the specification that states it.
|
||||
|
||||
## Load it into SQLite
|
||||
|
||||
```sh
|
||||
paperspec load --sqlite lab.db fixtures/packages/hale2026harmonic-damb
|
||||
```
|
||||
|
||||
```text
|
||||
hale2026harmonic-damb: 75 nodes
|
||||
```
|
||||
|
||||
The command validates the package first, creates `lab.db` with the tables of `sql/`, and loads the package.
|
||||
Query the result with any SQLite client; Python's own works:
|
||||
|
||||
```sh
|
||||
python -m sqlite3 lab.db "SELECT kind, COUNT(*) FROM nodes GROUP BY kind ORDER BY 2 DESC, kind LIMIT 3"
|
||||
```
|
||||
|
||||
```text
|
||||
('cell', 23)
|
||||
('sentence', 18)
|
||||
('row', 6)
|
||||
```
|
||||
|
||||
## Where next
|
||||
|
||||
- [Validate a package](../guides/validate-a-package.md), including how to try a correction without writing it.
|
||||
- [Load packages into SQLite](../guides/load-into-sqlite.md).
|
||||
- [Use the library](../guides/use-the-library.md) from Python.
|
||||
Reference in new issue
Block a user