From 8ae0679cfaa18375f5d962cc6de0e537d464f365 Mon Sep 17 00:00:00 2001 From: Alexandre Boucaud Date: Mon, 11 May 2026 22:11:09 +0200 Subject: [PATCH 1/2] Add boilerplate for docs versioning --- CLAUDE.md | 11 +++++++++++ justfile | 15 +++++++++++++++ pyproject.toml | 8 ++++++++ 3 files changed, 34 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 50232314..29affb6e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -77,6 +77,17 @@ tests/ # pytest — mirrors src/ structure pyproject.toml # hatchling + hatch-vcs, ASTRA + Snakemake as deps ``` +## Documentation versioning (mike) + +The whole docs site is versioned with [mike](https://github.com/squidfunk/mike) — specifically squidfunk's fork, which Zensical's versioning provider depends on. Each release deploys a full copy of the site to a subdirectory of the `gh-pages` branch (`/0.0.9/`, `/latest/`, etc.). Mike is enabled via `[project.extra.version] provider = "mike"` in `zensical.toml`; the version dropdown in the header is rendered natively. + +Release flow: after release, run `just docs-deploy X.Y.Z` — which runs `mike deploy --push --update-aliases X.Y.Z latest`. +This builds the site at the current commit and pushes a new version snapshot + updates the `latest` alias on `gh-pages`. + +First-time setup: after the first `docs-deploy`, run `just docs-set-default latest` once so the bare site root redirects to `/latest/`. + +Hosting: mike pushes to `gh-pages`. The hosting platform (Cloudflare Pages, GitHub Pages, etc.) must be configured to serve from `gh-pages`, not `main`. Without this, `mike deploy` runs successfully but the site doesn't pick up versioned URLs in production. + ## Development Commands ```bash diff --git a/justfile b/justfile index 42b41a54..af446cb7 100644 --- a/justfile +++ b/justfile @@ -67,6 +67,21 @@ docs-serve-port port="8080": docs-install docs-clean: rm -rf site/ +# Deploy a versioned snapshot of the docs to gh-pages via mike, updating +# the named alias (default: latest). Run after `just release`. +docs-deploy version alias='latest': docs-install + uv run mike deploy --push --update-aliases {{version}} {{alias}} + +docs-set-default alias='latest': + uv run mike set-default --push {{alias}} + +docs-versions: + uv run mike list + +docs-delete-version version: + uv run mike delete --push {{version}} + + # ── Package ──────────────────────────────────────────────────────────────────── # Build the wheel and sdist diff --git a/pyproject.toml b/pyproject.toml index 4f5f1212..37ceafab 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -40,8 +40,16 @@ dev = [ ] docs = [ "zensical>=0.0.33", + # squidfunk's mike fork — required by zensical's versioning provider. + # Not on PyPI; install from git. + "mike @ git+https://github.com/squidfunk/mike.git ; python_version >= '3.10'", ] +# Versioning is handled by mike (https://github.com/squidfunk/mike). +# Each version of the site is deployed as a subdirectory under site_url +# (e.g. /0.0.9/, /latest/). The picker is rendered natively in the header. +[project.extra.version] +provider = "mike" [project.scripts] lc = "lightcone.cli:main" From 62d1cdaf32c5aad7ef1e0c6a2730c72a2c3a9a1b Mon Sep 17 00:00:00 2001 From: Francois Lanusse Date: Fri, 21 Aug 2026 11:09:27 +0200 Subject: [PATCH 2/2] Integrate mike versioning: config in zensical.toml, mike-based deploy workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refreshes this branch onto post-#168 main and finishes the integration the original boilerplate left open: - Move [project.extra.version] provider = "mike" from pyproject.toml to zensical.toml — it is zensical site config, not package metadata, and an unknown "extra" key under [project] is invalid PEP 621. - Rework docs-deploy.yml: replace the actions/deploy-pages artifact upload with mike deploy --push --update-aliases latest plus mike set-default --push latest. Version comes from the release tag, or from a workflow_dispatch input for intermediate redeploys. - Update CLAUDE.md to describe the CI-driven release flow and the GitHub Pages "deploy from gh-pages branch" hosting requirement. Verified locally: uv sync --group docs installs squidfunk's mike fork (2.2.0+zensical-0.1.0) and zensical build succeeds with the version provider enabled (selector wiring present in the JS bundle). Note: repo Pages settings must be switched from "GitHub Actions" to "Deploy from a branch" / gh-pages once the first mike deploy has run. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_014PC18whir9otmXpQbaEgir --- .github/workflows/docs-deploy.yml | 83 ++++++++++++++++++++----------- CLAUDE.md | 7 +-- pyproject.toml | 6 --- zensical.toml | 7 +++ 4 files changed, 62 insertions(+), 41 deletions(-) diff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs-deploy.yml index 3b04f148..f650808d 100644 --- a/.github/workflows/docs-deploy.yml +++ b/.github/workflows/docs-deploy.yml @@ -1,33 +1,49 @@ name: Deploy Docs -# Deploys the docs site to GitHub Pages, which serves -# docs.lightconeresearch.org (custom domain configured in the repo's -# Pages settings). The site tracks the *released* CLI, not main: -# deploys happen on the same trigger as the PyPI publish, so the docs -# never document behavior that `pip install lightcone-cli` can't -# deliver yet. For an intermediate deploy (typo fix, clarification), -# trigger manually from the Actions tab (workflow_dispatch runs -# against the selected branch, main by default). +# Deploys a versioned snapshot of the docs to the gh-pages branch via +# mike; GitHub Pages serves that branch as docs.lightconeresearch.org +# (Settings → Pages must be set to "Deploy from a branch" / gh-pages). +# Each version lives under its own subdirectory (/0.4.1/, /0.5.0/, …) +# with the `latest` alias tracking the newest release, so old versions +# stay accessible after a new one ships. +# +# The site tracks the *released* CLI, not main: deploys happen on the +# same trigger as the PyPI publish, so the docs never document behavior +# that `pip install lightcone-cli` can't deliver yet. For an +# intermediate deploy (typo fix, clarification), trigger manually from +# the Actions tab — workflow_dispatch runs against the selected ref and +# redeploys the snapshot for the given version (defaults to the latest +# tag reachable from that ref). on: release: types: [published] workflow_dispatch: + inputs: + version: + description: "Docs version to (re)deploy, e.g. 0.4.1 (empty: latest tag on the selected ref)" + required: false + default: "" +# mike commits and pushes to the gh-pages branch. permissions: - contents: read - pages: write - id-token: write + contents: write +# Deploys append commits to gh-pages — queue them, never cancel one +# mid-push. concurrency: - group: pages - cancel-in-progress: true + group: docs-deploy + cancel-in-progress: false jobs: - build: + deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 + with: + # mike needs the gh-pages branch, and version resolution + # needs tags — fetch everything. + fetch-depth: 0 - name: Set up uv uses: astral-sh/setup-uv@v6 @@ -38,21 +54,28 @@ jobs: - name: Install docs dependencies run: uv sync --group docs - - name: Build docs - run: uv run zensical build + - name: Resolve docs version + id: version + env: + INPUT_VERSION: ${{ inputs.version }} + run: | + if [ -n "$INPUT_VERSION" ]; then + v="$INPUT_VERSION" + elif [ "${{ github.event_name }}" = "release" ]; then + v="${GITHUB_REF_NAME#v}" + else + v="$(git describe --tags --abbrev=0)" + v="${v#v}" + fi + echo "version=$v" >> "$GITHUB_OUTPUT" + echo "Deploying docs version $v" - - name: Upload Pages artifact - uses: actions/upload-pages-artifact@v3 - with: - path: site/ + - name: Configure git identity + run: | + git config user.name "github-actions[bot]" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" - deploy: - needs: build - runs-on: ubuntu-latest - environment: - name: github-pages - url: ${{ steps.deploy.outputs.page_url }} - steps: - - name: Deploy to GitHub Pages - id: deploy - uses: actions/deploy-pages@v4 + - name: Deploy versioned docs to gh-pages + run: | + uv run mike deploy --push --update-aliases "${{ steps.version.outputs.version }}" latest + uv run mike set-default --push latest diff --git a/CLAUDE.md b/CLAUDE.md index e97a241e..f5ed817e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -72,12 +72,9 @@ pyproject.toml # hatchling + hatch-vcs, ASTRA + Snakemake as deps The whole docs site is versioned with [mike](https://github.com/squidfunk/mike) — specifically squidfunk's fork, which Zensical's versioning provider depends on. Each release deploys a full copy of the site to a subdirectory of the `gh-pages` branch (`/0.0.9/`, `/latest/`, etc.). Mike is enabled via `[project.extra.version] provider = "mike"` in `zensical.toml`; the version dropdown in the header is rendered natively. -Release flow: after release, run `just docs-deploy X.Y.Z` — which runs `mike deploy --push --update-aliases X.Y.Z latest`. -This builds the site at the current commit and pushes a new version snapshot + updates the `latest` alias on `gh-pages`. +Release flow: `.github/workflows/docs-deploy.yml` runs on every published release — it runs `mike deploy --push --update-aliases X.Y.Z latest` (version taken from the tag) followed by `mike set-default --push latest`, so the bare site root always redirects to `/latest/`. For an intermediate redeploy of an existing version, trigger the workflow manually from the Actions tab. The `just docs-deploy` / `docs-set-default` / `docs-versions` / `docs-delete-version` recipes wrap the same mike commands for local use. -First-time setup: after the first `docs-deploy`, run `just docs-set-default latest` once so the bare site root redirects to `/latest/`. - -Hosting: mike pushes to `gh-pages`. The hosting platform (Cloudflare Pages, GitHub Pages, etc.) must be configured to serve from `gh-pages`, not `main`. Without this, `mike deploy` runs successfully but the site doesn't pick up versioned URLs in production. +Hosting: mike pushes to `gh-pages`. GitHub Pages (which serves docs.lightconeresearch.org) must be configured to "Deploy from a branch" / `gh-pages` in the repo's Pages settings, not via the Actions artifact deploy. Without this, `mike deploy` runs successfully but the site doesn't pick up versioned URLs in production. ## Development Commands diff --git a/pyproject.toml b/pyproject.toml index 22e4df16..3a359254 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -59,12 +59,6 @@ docs = [ "mike @ git+https://github.com/squidfunk/mike.git ; python_version >= '3.10'", ] -# Versioning is handled by mike (https://github.com/squidfunk/mike). -# Each version of the site is deployed as a subdirectory under site_url -# (e.g. /0.0.9/, /latest/). The picker is rendered natively in the header. -[project.extra.version] -provider = "mike" - [project.scripts] lc = "lightcone.cli:main" diff --git a/zensical.toml b/zensical.toml index 0b6be05c..ab336ee8 100644 --- a/zensical.toml +++ b/zensical.toml @@ -52,6 +52,13 @@ nav = [ {"ASTRA docs" = "https://astra-spec.org/latest/"}, ] +# Versioning is handled by mike (squidfunk's fork; see the docs +# dependency group). Each version of the site is deployed as a +# subdirectory of the gh-pages branch (e.g. /0.4.1/, /latest/). +# The version picker is rendered natively in the header. +[project.extra.version] +provider = "mike" + [project.theme] variant = "modern" logo = "assets/logo.svg"