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:
alexmandClaude committed 2026-10-19 04:23:49 -04:00
1 parent bdbf03ebee
commit 30d310f64d
37 files changed
+1005 -83

No files matched your search

+56
View File
@@ -0,0 +1,56 @@
# Builds the Zensical documentation strictly (a broken link or a page missing from the navigation fails the job) and,
# on main, copies it to /srv/www/docs/paperspec, which serves https://docs.scient.ing/paperspec/.
# The linux-base runner mounts the host's /srv/www into its job containers, so publishing is a local copy.
name: docs
on:
push:
branches: [main, dev]
paths:
- "docs/**"
- "zensical.toml"
- "README.md"
- "CHANGELOG.md"
- "src/**"
- ".gitea/workflows/docs.yml"
workflow_dispatch:
permissions:
contents: read
concurrency:
group: docs-${{ gitea.ref }}
cancel-in-progress: true
defaults:
run:
shell: bash
env:
SITE_ROOT: /srv/www/docs
SITE_SLUG: paperspec
jobs:
docs:
runs-on: linux-base
container:
image: git.scient.ing/infra/linux-base:26.10.7
timeout-minutes: 15
steps:
- uses: actions/checkout@v4
with:
persist-credentials: false
- name: Build the documentation, strictly
run: pixi run --locked -e docs docs-build
- name: Publish the documentation
if: github.ref == 'refs/heads/main'
run: |
if [ ! -d "$SITE_ROOT" ]; then
echo "$SITE_ROOT is not mounted on this runner, so the docs were built but not published."
exit 0
fi
case "$SITE_SLUG" in
''|*/*|.*) echo "SITE_SLUG must be a plain folder name, not '$SITE_SLUG'." >&2; exit 1 ;;
esac
if [ ! -f build/docs/index.html ] || [ ! -f build/docs/404.html ]; then
echo "build/docs has no index.html or 404.html, so it was not published." >&2
exit 1
fi
# Same copy as the other studio sites: unchanged files keep their Last-Modified and ETag, and the
# changes apply together at the end of the copy.
rsync --recursive --links --perms --chmod=D755,F644 --checksum --delay-updates --delete-delay --stats \
build/docs/ "$SITE_ROOT/$SITE_SLUG/"
+29 -11
View File
@@ -1,16 +1,18 @@
# Publishes the paperspec Python package to this instance's PyPI registry when a version tag (v0.1.1) is
# pushed; see deploy/README.md for the secrets it needs and how to install from the registry.
# The package version comes from the tag through setuptools-scm, so the job refuses to upload unless the
# built version equals the tag. Run it by hand only on a tag, for example after adding the secrets.
# Publishes the paperspec wheel and sdist to this Gitea instance's PyPI registry when a version tag (v1.2.3) is pushed,
# and creates the Gitea release with both files attached. The version is the tag's: setuptools-scm computes it
# from git (hence the full-history checkout), and the job refuses to upload unless the built version equals the
# tag, so tag the commit you mean to release. Run it by hand only on a tag.
# Needs the organization secrets PACKAGE_USER and PACKAGE_TOKEN (a token with the write:package scope).
# Install side: README.md ("Installing") and deploy/README.md name the registry index.
name: publish
on:
push:
tags: ["v*"]
tags: ["v[0-9]*"]
workflow_dispatch:
permissions:
contents: read
concurrency:
group: publish-${{ github.ref }}
group: publish-${{ gitea.ref }}
cancel-in-progress: false
defaults:
run:
@@ -23,14 +25,14 @@ jobs:
timeout-minutes: 30
env:
REGISTRY: ${{ github.server_url }}/api/packages/${{ github.repository_owner }}/pypi
API: ${{ github.server_url }}/api/v1/repos/${{ github.repository }}
steps:
- name: Require a version tag
run: |
if [[ "$GITHUB_REF" != refs/tags/v* ]]; then
echo "Publish runs on a version tag such as v0.1.1; $GITHUB_REF is not one."
echo "Publish runs on a version tag such as v1.2.3; $GITHUB_REF is not one."
exit 1
fi
# The whole history, so setuptools-scm finds the tag and computes the release version.
- uses: actions/checkout@v4
with:
fetch-depth: 0
@@ -38,7 +40,7 @@ jobs:
- name: Check the repository
run: pixi run --locked check
- name: Build the sdist and wheel
run: pixi run --locked -e dev dist
run: pixi run --locked -e release dist
- name: Confirm the built version is the tag
run: |
tag="${GITHUB_REF_NAME#v}"
@@ -50,7 +52,7 @@ jobs:
exit 1
fi
- name: Check the package metadata
run: pixi run --locked -e dev twine check --strict dist/*
run: pixi run --locked -e release twine check --strict dist/*
# --skip-existing makes a rerun on the same tag succeed instead of failing on the files already there.
- name: Upload to the package registry
env:
@@ -62,5 +64,21 @@ jobs:
echo "The secrets PACKAGE_USER and PACKAGE_TOKEN are not set; deploy/README.md says how."
exit 1
fi
pixi run --locked -e dev twine upload --non-interactive --skip-existing dist/*
pixi run --locked -e release twine upload --non-interactive --skip-existing dist/*
echo "Published to $REGISTRY: pip install --index-url $REGISTRY/simple/ paperspec"
- name: Create the release and attach the files
env:
TOKEN: ${{ secrets.RELEASE_TOKEN || secrets.GITHUB_TOKEN }}
run: |
# A release is a "## 0.1.0" or "### 0.1.1" heading in CHANGELOG.md; its notes run to the next heading.
notes="$(awk -v v="${GITHUB_REF_NAME#v}" '
/^##+ / { if (found) exit; if (index($0, v)) found = 1; next }
found { print }' CHANGELOG.md)"
body="$(printf '%s\n' "${notes:-See CHANGELOG.md.}" | jq -Rs .)"
release_id="$(curl -fsS -X POST "$API/releases" \
-H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
-d "{\"tag_name\": \"$GITHUB_REF_NAME\", \"name\": \"$GITHUB_REF_NAME\", \"body\": $body}" | jq .id)"
for f in dist/*; do
curl -fsS -X POST "$API/releases/$release_id/assets?name=$(basename "$f")" \
-H "Authorization: token $TOKEN" -F "attachment=@$f"
done