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
+15
-7
@@ -56,16 +56,16 @@ The environment in `.pixi/envs` is cached between runs under the hash of `pixi.l
|
||||
## Publish the Python package
|
||||
|
||||
The Python package `paperspec` holds the reference implementation and the `paperspec` command.
|
||||
The workflow `.gitea/workflows/publish.yml` publishes it to the PyPI registry of the Gitea instance, `https://git.scient.ing/api/packages/infra/pypi`, when a version tag such as `v0.1.1` is pushed.
|
||||
It checks the repository, builds the sdist and the wheel with `pixi run -e dev dist`, confirms that the version setuptools-scm computed is the tag's, checks the metadata with twine, and uploads both files.
|
||||
The workflow `.gitea/workflows/publish.yml` publishes it to the PyPI registry of the Gitea instance, `https://git.scient.ing/api/packages/papers/pypi`, when a version tag such as `v0.1.1` is pushed.
|
||||
It checks the repository with `pixi run check` (the code checks, the Markdown lint and `paperspec check`), builds the sdist and the wheel with `pixi run -e release dist`, confirms that the version setuptools-scm computed is the tag's, checks the metadata with twine, uploads both files, and creates the Gitea release with the files attached and the notes taken from the section of `CHANGELOG.md` whose heading contains the version.
|
||||
The package version is the version of this code; the formats keep the version that `CHANGELOG.md` and `pixi.toml` state.
|
||||
|
||||
### Set it up once
|
||||
|
||||
1. Pick the account the workflow publishes as, a bot account or your own, and make it a member of a team in the `infra` organization with write access to packages.
|
||||
1. Pick the account the workflow publishes as, a bot account or your own, and make it a member of a team in the `papers` organization with write access to packages.
|
||||
2. Signed in as that account, create an access token under Settings, Applications, with the `write:package` scope.
|
||||
3. In this repository's Settings, Actions, Secrets, add `PACKAGE_USER` with the account's user name and `PACKAGE_TOKEN` with the token.
|
||||
Organization secrets work as well, for every repository in `infra`.
|
||||
Organization secrets work as well, for every repository in `papers`.
|
||||
Gitea refuses secret names that start with `GITEA_` or `GITHUB_`.
|
||||
4. After the first upload, link the package to this repository in the package's settings, so it shows on the repository's Packages tab.
|
||||
|
||||
@@ -91,7 +91,7 @@ With pixi, in `pixi.toml`:
|
||||
|
||||
```toml
|
||||
[pypi-dependencies]
|
||||
paperspec = { version = ">=0.1.1", extras = ["tools"], index = "https://git.scient.ing/api/packages/infra/pypi/simple" }
|
||||
paperspec = { version = ">=0.1.1", extras = ["tools"], index = "https://git.scient.ing/api/packages/papers/pypi/simple" }
|
||||
```
|
||||
|
||||
With uv, in `pyproject.toml`:
|
||||
@@ -99,7 +99,7 @@ With uv, in `pyproject.toml`:
|
||||
```toml
|
||||
[[tool.uv.index]]
|
||||
name = "scienting"
|
||||
url = "https://git.scient.ing/api/packages/infra/pypi/simple"
|
||||
url = "https://git.scient.ing/api/packages/papers/pypi/simple"
|
||||
explicit = true
|
||||
|
||||
[tool.uv.sources]
|
||||
@@ -109,12 +109,20 @@ 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/infra/pypi/simple/ --extra-index-url https://pypi.org/simple/ "paperspec[tools]"
|
||||
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`.
|
||||
A git pin to a commit, as `pixi.toml` and `pyproject.toml` can also express, keeps working and needs no registry.
|
||||
|
||||
## Publish the package documentation
|
||||
|
||||
The pages for the Python package and its command are in `docs/package/` and are built with Zensical, separately from the format site above.
|
||||
The workflow `.gitea/workflows/docs.yml` builds them strictly with `pixi run -e docs docs-build` into `build/docs` on every push to `main` and `dev`, and on `main` copies them to `/srv/www/docs/paperspec`, which serves <https://docs.scient.ing/paperspec/>.
|
||||
A broken link, or a page missing from the navigation in `zensical.toml`, fails the build.
|
||||
The copy is local, like the site's: the runner mounts the host's `/srv/www`.
|
||||
Serving `/srv/www/docs` at `docs.scient.ing` is the same kind of Caddy entry as [Caddyfile](Caddyfile), and not part of this repository.
|
||||
|
||||
## Distributing document packages
|
||||
|
||||
A zipped package is an ordinary file, and the site serves the fixtures as such.
|
||||
|
||||
Reference in new issue
Block a user