Add PyPI Trusted Publishing workflow and release documentation

[Copilot]

Automates PyPI publishing via GitHub Actions using OIDC Trusted Publishing — no stored API tokens required. Publishing triggers on GitHub Release publication.

Workflow (.github/workflows/publish.yml)

• build job: runs python -m build, smoke-checks the wheel (import point_collocation), uploads artifacts
• publish job: publishes sdist + wheel via pypa/gh-action-pypi-publish@release/v1 with id-token: write / contents: read permissions

Docs (docs/releasing.md)

Step-by-step release guide covering:

• Version bump in pyproject.toml → tag → GitHub Release
• One-time PyPI Trusted Publisher registration (required before first publish — owner must add this on PyPI under Settings → Trusted Publishers)
• Troubleshooting: 403/OIDC misconfiguration, duplicate version, metadata errors, smoke check failures

Nav (mkdocs.yml)

Added Releasing entry to the documentation site navigation.

Note: The automated publish will fail until a maintainer registers GitHub as a Trusted Publisher on the PyPI project page (exact steps in docs/releasing.md).

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Set up PyPI publishing workflow (Trusted Publishing) + release process</issue_title>
<issue_description>Title: Set up PyPI publishing workflow (Trusted Publishing) + release process

Goal

Automate publishing this package to PyPI when we create a GitHub Release (tagged version). Prefer PyPI Trusted Publishing (OIDC) using pypa/gh-action-pypi-publish so we don’t store PyPI tokens in GitHub Secrets.

Tasks

Confirm packaging is ready

Ensure we have a working pyproject.toml with correct metadata:

[project].name point-collocation

version is set

readme / license / requires-python, etc.

Ensure src/ layout imports work (e.g., import point_collocation).

Add a publish workflow
Create .github/workflows/publish.yml that:

Triggers on release: { types: [published] }

Builds sdist + wheel using python -m build

Publishes using pypa/gh-action-pypi-publish@release/v1

Uses Trusted Publishing permissions:

permissions: id-token: write

contents: read

Include a small “smoke check” step that installs the built wheel locally and imports the package.

Reference docs:

Packaging guide for publishing from GitHub Actions

gh-action-pypi-publish trusted publishing requirements

PyPI trusted publisher usage docs

Document the release steps
Update README.md (or add docs/releasing.md) with:

how to bump version

how to create a tag / GitHub Release

what triggers publishing

troubleshooting tips (common errors: missing trusted publisher, version already exists, metadata issues)

Acceptance criteria

A GitHub Release publishes a wheel + sdist to PyPI successfully.

Workflow uses Trusted Publishing (OIDC) with id-token: write and no stored PyPI token.

Documentation exists describing the release/publish process.</issue_description>

Comments on the Issue (you are @copilot in this section)

@eeholmes Repo secrets you need to create Preferred (Trusted Publishing)

None.
With Trusted Publishing, you do not store a PyPI API token in GitHub Secrets. Instead, you configure a Trusted Publisher on PyPI that trusts this GitHub repo + workflow.

What you do need to configure (on PyPI, not GitHub):

PyPI project → Settings → Trusted Publishers

Add GitHub as publisher and specify:

owner/org

repo name

workflow file path (e.g. .github/workflows/publish.yml)

environment (if you choose to use one)

(Your agent can add the workflow, but you’ll still need to click through PyPI once to register the trusted publisher.)</comment_new>

• Fixes Set up PyPI publishing workflow (Trusted Publishing) + release process #20

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.