From 3497fbbf8d070cb5f932e02c3ed30df2fb9519ce Mon Sep 17 00:00:00 2001
From: Manuel Polo <mrmx@users.noreply.github.com>
Date: Sun, 18 Oct 2026 21:04:54 +0000
Subject: [PATCH] ci: attach the generated pdoc to each release

Attach the generated pdoc of each release to that release, as a tar.gz with
its checksum, so the QTSurfer website can host the reference documentation
itself instead of relying on GitHub Pages.

The new reference-docs workflow runs after the job that creates the GitHub
Release (see publish.yml) and can also be started by hand with the tag of a release
that already exists. The existing Pages job is untouched.
---
 .github/workflows/publish.yml        |  8 +++++
 .github/workflows/reference-docs.yml | 52 ++++++++++++++++++++++++++++
 2 files changed, 60 insertions(+)
 create mode 100644 .github/workflows/reference-docs.yml

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 6a99117..72b72ef 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -80,3 +80,11 @@ jobs:
           gh release create "$GITHUB_REF_NAME" \
             --title "$GITHUB_REF_NAME" \
             --notes-file /tmp/release-notes.md
+
+  reference-docs:
+    needs: release
+    permissions:
+      contents: write
+    uses: ./.github/workflows/reference-docs.yml
+    with:
+      tag: ${{ github.ref_name }}
diff --git a/.github/workflows/reference-docs.yml b/.github/workflows/reference-docs.yml
new file mode 100644
index 0000000..1b0aa7d
--- /dev/null
+++ b/.github/workflows/reference-docs.yml
@@ -0,0 +1,52 @@
+name: Reference documentation archive
+
+# Attaches the generated pdoc of a release to that release, as a tar.gz with its checksum, so the
+# QTSurfer website can publish it. It runs after every release (see publish.yml) and by hand to build
+# the archive of a release that already exists.
+on:
+  workflow_call:
+    inputs:
+      tag:
+        description: Release tag to document
+        required: true
+        type: string
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Existing release tag to document
+        required: true
+        type: string
+
+permissions:
+  contents: write
+
+jobs:
+  archive:
+    runs-on: ubuntu-latest
+    env:
+      TAG: ${{ inputs.tag }}
+      GH_TOKEN: ${{ github.token }}
+    steps:
+      - name: Check that the release exists
+        run: gh release view "$TAG" --repo "$GITHUB_REPOSITORY" > /dev/null
+      - uses: actions/checkout@v4
+        with:
+          ref: refs/tags/${{ inputs.tag }}
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Sync dependencies
+        run: uv sync --frozen
+      - name: Generate docs
+        run: ./scripts/docs.sh
+      - name: Package the documentation
+        run: |
+          name="api-client-python-docs-${TAG}"
+          tar -czf "${name}.tar.gz" -C docs .
+          sha256sum "${name}.tar.gz" > "${name}.tar.gz.sha256"
+      - name: Attach it to the release
+        run: |
+          name="api-client-python-docs-${TAG}"
+          gh release upload "$TAG" "${name}.tar.gz" "${name}.tar.gz.sha256" \
+            --repo "$GITHUB_REPOSITORY" --clobber