docs: simplify build + zrepl.github.io publishing (#913)

This PR simplifies how we build and publish docs:

- **Publish from `master` branch, retire `stable` branch.** The `stable`
branch was a manual step in the release process and often out of date.
Docs are now built and published directly from `master`.
Release-specific docs are available in the `zrepl-noarch.tar` asset on
each GitHub release.

- **build dependencies**: use `uv` for dependency management

- **zrepl.github.io: retire multi-version docs**: before this PR we used
`sphinx-multiversion` to publish multiple docs versions to
`zrepl.github.io`. This was never worth the pain, so, this PR removes it
in order to simplify stuff. Old docs are available in the GitHub
releases, and the docs now have a version dropdown that links there for
a hand-curated set of versions.

- **GitHub pages repo checkout**: use HTTPS because that's what I use
these days for all things GitHub. Switch CircleCI to a fine-grained PAT.

Refs
- docs bug https://github.com/zrepl/zrepl/issues/895
  - links to config examples should work again after this PR

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

README.md

@@ -56,8 +56,8 @@ There is a CI check that ensures Git state is clean, i.e., code generation has b
 
 #### Docs
 
-Set up a Python environment that has `docs/requirements.txt` installed via `pip`.
-Use a  [venv](https://docs.python.org/3/library/venv.html) to avoid global state.
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then run `make docs`.
+uv automatically manages Python and dependencies.
 
 ### Testing
 
@@ -90,17 +90,28 @@ There is a git tag for each zrepl release, usually `vMAJOR.MINOR.0`.
 We don't move git tags once the release has been published.
 
 The procedure to issue a release is as follows:
-* Issue the source release:
-  * Git tag the release on the `master` branch.
+
+* Prepare the release (as a PR to `master`):
+  * Finalize `docs/changelog.rst` for the release.
+  * Merge the PR. Docs are auto-published to zrepl.github.io on merge.
+* Tag the release:
+  * Git tag the release on the `master` branch (e.g., `vMAJOR.MINOR.0`).
   * Push the tag.
-  * Run `./docs/publish.sh` to re-build & push zrepl.github.io.
-* Issue the official binary release:
-  * Run the `release` pipeline (triggered via CircleCI API)
-  * Download the artifacts to the release manager's machine.
-  * Create a GitHub release, edit the changelog, upload all the release artifacts, including .rpm and .deb files.
-  * Issue the GitHub release.
+* Build and publish:
+  * Run the `release` pipeline (trigger via CircleCI UI).
+  * Download artifacts: `make download-circleci-release BUILD_NUM=<circleci-build-number>`
+  * Create GitHub release and upload artifacts:
+    ```bash
+    gh release create vX.Y.Z --title "vX.Y.Z" --notes "See changelog" --draft
+    gh release upload vX.Y.Z artifacts/release/*
+    ```
+  * Review the draft release, edit the changelog, then publish.
   * Add the .rpm and .deb files to the official zrepl repos.
     * Code for management of these repos: https://github.com/zrepl/package-repo-ops (private repo at this time)
+* Update docs version list:
+  * Update `docs/_templates/versions.html` with the new release.
+  * Verify the link to `zrepl-noarch.tar` in the GitHub release works.
+  * Merge to `master` (docs auto-publish).
 
 #### Patch releases, Go toolchain updates, APT/RPM Package rebuilds
 
@@ -161,6 +172,17 @@ Update the CI configuration `.circleci/config.yml`:
 - Update Go version references (we reference the minimum and max supported version)
 - Set `Makefile` `RELEASE_GOVERSION` to the new Go version
 
+Update docs build tooling:
+- Update `uv` version in `.circleci/config.yml` (search for `astral.sh/uv/` and cache keys containing the version)
+- Check if there's now a CircleCI orb for uv that we could use
+- Update Python version in `docs/.python-version`
+
+Update docs dependencies (Sphinx, sphinx-rtd-theme):
+- Check current versions in `docs/pyproject.toml`
+- Review upstream changelogs for breaking changes
+- Update version constraints in `pyproject.toml` and the `uv` lockfile (see [uv docs on dependencies](https://docs.astral.sh/uv/concepts/projects/dependencies/)):
+- Test locally with `make docs`
+
 Kick a full CI pipeline run (`do_ci=true` and `do_release=true`).
 
 Merge PR with merge commit.