Versioned docs with a version switcher

[cailmdaley]

Why

The docs site (cosmostat.github.io/shapepipe) publishes only from master, which is currently ~78 commits behind develop. So the public docs describe an old release while everyone actually runs develop, and several recently written pages — container.md, canfar.md, and four others — have never been published at all (container.html → 404 today).

Rather than just flipping the trigger to develop (which would make the public site silently track integration), this makes the site versioned, with a switcher to move between releases and the development tip — the conventional answer when both "what's released" and "what's current" matter.

What

gh-pages layout — additive, and non-destructive to existing URLs:

Ref	Publishes to
master / main	site root	stable — every current …/installation.html link keeps working
develop	/latest/	new; this is what makes the unpublished pages reachable
tags v*	/<tag>/	e.g. /v1.1.0/, additive

A switcher.json at the site root drives the dropdown.

cd.yml now triggers on master/main, develop, and v* tags; resolves the ref to a version slug; builds each ref in its own dev image and deploys into that ref's directory with keep_files: true, so a deploy only ever writes its own slice and never clobbers the others. Building per-ref (rather than one shared env across all refs, as sphinx-multiversion uses) is deliberate: autodoc imports shapepipe, so an old tag must build against its own dependencies — which it does, at its own time.

Pull requests that touch the docs now build + upload the HTML as an artifact but do not deploy — so a broken docs build is caught before merge, and reviewers can download and preview the rendered site. (This PR exercises that path on itself.)

conf.py gains the switcher config and now reads the version from installed package metadata instead of a hand-maintained string that had already gone stale (1.0.1 vs the actual 1.1.0).

Verification

Local sphinx-book-theme 1.2.0 build: the switcher chrome renders, and json_url (…/switcher.json) and version_match (from the DOCS_VERSION the workflow sets) are wired correctly. The populated dropdown resolves at runtime from the deployed switcher.json, so it's fully observable only after the first deploy — which is safe: the first develop deploy only adds /latest/ + /switcher.json and leaves the existing root untouched.

Note — a small policy shift

After this lands, the public docs site will publish develop as latest (alongside stable + tagged releases) — so our in-development docs become publicly visible. That seems right for an actively developed pipeline with a growing external audience, but it's worth a conscious nod since it changes what doc readers see.

Two follow-ups it enables, not included here: (1) seeding switcher.json with the first real release entry when the next version is tagged; (2) a one-time master release to refresh the root with the current docs.

— Claude on behalf of Cail