[MarTrepodi]

Description

Publishes the docs site as versioned docs with mike, so the stable 2.x line and the upcoming 3.x pre-releases can be published side by side at https://swgoh-utils.github.io/comlink-python/ behind Material's version picker.

Docs now deploy from release/* branches, and each branch publishes its own version:

Branch	Docs version	Alias	Picker title
release/v2.5.0 (highest stable deployed)	2.5.0	latest (site default)	2.5.0
release/v2.4.2 (after 2.5.0 is deployed)	2.4.2	none	2.4.2
release/v3.0.0a2	3.0.0a2	alpha	3.0.0a2 (alpha)
release/v3.0.0rc1	3.0.0rc1	rc	3.0.0rc1 (rc)
release/v3.0.0a2.dev1	3.0.0a2.dev1	dev	3.0.0a2.dev1 (dev)
release/next	job fails with ::error:: (not a PEP 440 version)

• latest and the root URL follow the highest stable version already deployed, not the most recent push. A later patch to an older line therefore doesn't take latest.
• A pre-release takes its alias (alpha/beta/rc/dev) only when it is the highest deployed version of that kind, and it never changes latest.

Changes

• .github/workflows/docs.yml:
  • Replaces the single-version GitHub Actions Pages deploy from main with mike deploy --push --update-aliases to a gh-pages branch.
  • Triggers on pushes to release/** (same path filters) and on workflow_dispatch.
  • The job runs only when github.repository == 'swgoh-utils/comlink-python' and the ref is refs/heads/release/*, so forks and other refs never publish.
  • Pushes to main, develop and tags no longer deploy.
  • It uses contents: write, a gh-pages concurrency group, fetch-depth: 0, a strict build before deploying, and no setup-uv cache in the publishing job.
• .github/scripts/docs_version.py: a new helper that turns the branch name and mike list --json into version / alias / title / set_default / prerelease, using packaging.version.Version. It is covered by tests/unit/test_docs_version.py.
• mkdocs.yml + overrides/main.html:
  • extra.version.provider: mike adds the version picker.
  • A pre-release banner is driven by DOCS_PRERELEASE.
  • An "older release" banner shows when viewing a version that isn't latest.
• pyproject.toml / uv.lock: adds mike>=2.2.0 to the docs dependency group.
• ci.yml: the required Docs check now builds with --strict, matching the deploy job.
• .gitignore / .pre-commit-config.yaml:
  • Un-ignores .github/scripts/; a bare scripts/ rule was hiding it.
  • check-yaml skips mkdocs.yml, whose !ENV tag the safe loader rejects; the strict docs build validates it instead.
• Docs fix (README.md, docs/migration.md): these told readers to catch httpx.RequestError, but the clients re-raise it as SwgohComlinkException, so that handler never fires. They now point at SwgohComlinkException and the SwgohComlinkHTTPError family.
• CONTRIBUTING.md: adds a "Publishing the docs" section covering the version and alias rules, release timing, and the one-time cutover.

Related Issues

None. This prepares for folding the 2.5.x product line and the experimental 3.x line into this repository.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Refactor (code change that neither fixes a bug nor adds a feature)
• Performance improvement
• Documentation
• Tests
• CI / build / dependencies

Breaking Changes

There's no change to the library. The published docs URLs change once the cutover below is done:

• Pages move under a version folder, e.g. /comlink-python/2.5.0/<page>/.
• The root URL redirects to latest.
• Old deep links to specific pages (from Discord, issues, etc.) will 404 unless redirects are added.

Checklist

• This PR targets the develop branch (only release PRs target main)
• My commits follow the Conventional Commits / Angular convention (feat:, fix:, refactor:, etc.) — they become the changelog
• I have not edited CHANGELOG.md by hand (it is generated from commit messages)
• I have added/updated docstrings with type hints for any new or changed public methods (n/a: no public API changes)
• I have updated the docs (README.md, docs/, examples/) if user-facing behavior changed
• I have added unit tests that cover my changes (mocked, not requiring a live comlink service)
• Tests pass (uv run pytest tests/): to be confirmed by CI
• Ruff linter and formatter pass (uv run ruff check src/ tests/ and uv run ruff format --check src/ tests/): to be confirmed by CI
• Type check passes (uv run ty check src/swgoh_comlink/): to be confirmed by CI
• I have not bundled unrelated changes in this PR

Testing

• docs_version.py: 26 unit tests, plus direct runs on sample branches; the table above shows the actual output.
• Local mike run (no --push) into a throwaway gh-pages, deploying 2.5.0, then 3.0.0a2, then 2.4.2:
  • latest and the root redirect stayed on 2.5.0, and alpha pointed at 3.0.0a2.
  • The picker listed every version, and switching versions kept the current page.
  • Both banners rendered.
• docs.yml: checked with actionlint, and mkdocs build --strict passes.
• Still to confirm: the full test suite, ruff and ty were run locally while developing, and this PR's required checks will confirm them.

Reviewers, please verify:

• the version and alias rules in docs_version.py;
• the job condition in docs.yml;
• the cutover order below.

Cutover after merge (maintainer, one time)

1. Get the new workflow onto main through the normal release flow, or a direct PR to main as with docs(api): order client pages for first-time readers #190. Until then, main keeps deploying the single-version site through GitHub Actions.
2. Allow gh-pages to deploy: add gh-pages to the github-pages environment's deployment branch policy. Today it allows only main, and branch-based Pages builds would be blocked.
3. Publish 2.5.0: push a release/v2.5.0 branch that has the released 2.5.0 docs plus this workflow, i.e. main with this PR merged in. The deploy creates gh-pages with 2.5.0, latest, and the root redirect. If the push doesn't change a watched path, run "Deploy docs" by hand on that branch.
4. Switch Pages to the branch: in Settings → Pages, change the source from "GitHub Actions" to "Deploy from a branch: gh-pages / (root)".
5. Check the live site: the root redirects to 2.5.0/ and versions.json lists 2.5.0 with latest.
6. Publish the 3.x alpha: push release/v3.0.0a2, with the v3 equivalent of this change, to publish 3.0.0a2 (alpha).

Release timing: prepare-release.yml pushes release/vX.Y.Z using the workflow's built-in token, and GitHub doesn't start workflow runs from those pushes. So stable docs need a manual "Deploy docs" run on that branch. A follow-up could have prepare-release.yml call gh workflow run docs.yml --ref release/vX.Y.Z; workflow_dispatch events from that token do start runs. delete_branch_on_merge removes release branches after their PR merges, but the published versions stay on gh-pages.

🤖 Generated with Claude Code