fix(optimistic): apply optimistic UI patch client-side (closes #16) (… #34
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Docs | |
| # Deploy API documentation to GitHub Pages via GitHub Actions. | |
| # | |
| # Versioning strategy | |
| # ─────────────────── | |
| # • Push to master → docs deployed under /main/ | |
| # • Push of v* tag → docs deployed under /{tag}/ (e.g. /v0.1.0/) | |
| # AND /latest/ is updated to point at the new tag | |
| # • Older versions are never removed — the gh-pages branch acts as a | |
| # persistent version store. The deploy job checks it out, merges the | |
| # new version in, then uploads the whole tree with upload-pages-artifact | |
| # so GitHub Pages (Actions mode) serves it. | |
| # • Root index.html and versions.json are regenerated on every deploy. | |
| # • Each page carries a JS version-switcher that reads versions.json. | |
| # | |
| # GitHub Pages setup (one-time, in repo Settings → Pages): | |
| # Source → GitHub Actions (NOT "Deploy from a branch") | |
| on: | |
| push: | |
| branches: [master, main] | |
| tags: ["v*.*.*"] | |
| workflow_dispatch: | |
| inputs: | |
| version_override: | |
| description: "Version label (leave blank to derive from branch/tag)" | |
| required: false | |
| default: "" | |
| concurrency: | |
| group: docs-deploy | |
| cancel-in-progress: false # never cancel a running deploy mid-flight | |
| # ── Job 1: Build ────────────────────────────────────────────────────────────── | |
| # | |
| # Generates pdoc HTML for the current commit and uploads it as a workflow | |
| # artifact. No write permissions needed here. | |
| jobs: | |
| build: | |
| name: Build Docs | |
| runs-on: ubuntu-latest | |
| outputs: | |
| version-label: ${{ steps.version.outputs.label }} | |
| is-release: ${{ steps.version.outputs.is_release }} | |
| steps: | |
| - uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 | |
| - uses: actions/setup-python@v5 | |
| with: | |
| python-version: "3.12" | |
| - name: Install pdoc and project | |
| run: | | |
| pip install pdoc | |
| pip install -e ".[dev,django,websockets]" | |
| - name: Determine version label | |
| id: version | |
| run: | | |
| if [ -n "${{ github.event.inputs.version_override }}" ]; then | |
| LABEL="${{ github.event.inputs.version_override }}" | |
| IS_RELEASE="false" | |
| elif [[ "$GITHUB_REF" == refs/tags/* ]]; then | |
| LABEL="${GITHUB_REF#refs/tags/}" | |
| IS_RELEASE="true" | |
| else | |
| LABEL="main" | |
| IS_RELEASE="false" | |
| fi | |
| echo "label=${LABEL}" >> "$GITHUB_OUTPUT" | |
| echo "is_release=${IS_RELEASE}" >> "$GITHUB_OUTPUT" | |
| echo "Building docs for version: ${LABEL}" | |
| - name: Generate docs | |
| run: python docs/make.py --output-dir generated | |
| # Upload only the new version's output — the deploy job merges it | |
| # with the existing version store. | |
| - uses: actions/upload-artifact@v4 | |
| with: | |
| name: docs-${{ steps.version.outputs.label }} | |
| path: generated/ | |
| retention-days: 7 | |
| # ── Job 2: Deploy ───────────────────────────────────────────────────────────── | |
| # | |
| # 1. Checks out the gh-pages branch (version store). | |
| # 2. Downloads the artifact from the build job. | |
| # 3. Copies the new version into the store. | |
| # 4. Regenerates versions.json and root index.html. | |
| # 5. Uploads the full store with upload-pages-artifact. | |
| # 6. Deploys via actions/deploy-pages (OIDC — no PAT needed). | |
| # 7. Pushes the updated store back to gh-pages so future runs see all versions. | |
| deploy: | |
| name: Deploy to GitHub Pages | |
| needs: build | |
| runs-on: ubuntu-latest | |
| permissions: | |
| contents: write # push updated version store to gh-pages branch | |
| pages: write # upload Pages artifact | |
| id-token: write # OIDC token for Pages deployment | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deploy.outputs.page_url }} | |
| steps: | |
| # ── Checkout source (for docs/ scripts) ─────────────────────────── | |
| - uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 | |
| # ── Prepare the gh-pages version-store worktree ─────────────────── | |
| - name: Prepare gh-pages version store | |
| run: | | |
| git config user.name "github-actions[bot]" | |
| git config user.email "github-actions[bot]@users.noreply.github.com" | |
| git fetch origin gh-pages:gh-pages 2>/dev/null || true | |
| if git show-ref --quiet refs/heads/gh-pages; then | |
| git worktree add gh-pages-dir gh-pages | |
| else | |
| # First run: create the orphan branch | |
| git worktree add --orphan -b gh-pages gh-pages-dir | |
| cd gh-pages-dir | |
| git commit --allow-empty -m "chore: initialise gh-pages version store" | |
| cd .. | |
| fi | |
| # ── Merge new version into the store ────────────────────────────── | |
| - uses: actions/download-artifact@v4 | |
| with: | |
| name: docs-${{ needs.build.outputs.version-label }} | |
| path: downloaded-docs/ | |
| - name: Copy new version into store | |
| run: | | |
| LABEL="${{ needs.build.outputs.version-label }}" | |
| DEST="gh-pages-dir/${LABEL}" | |
| rm -rf "${DEST}" | |
| mkdir -p "${DEST}" | |
| cp -r downloaded-docs/. "${DEST}/" | |
| - name: Update latest symlink (releases only) | |
| if: needs.build.outputs.is-release == 'true' | |
| run: | | |
| cd gh-pages-dir | |
| rm -rf latest | |
| ln -sfn "${{ needs.build.outputs.version-label }}" latest | |
| - name: Regenerate versions.json and root index | |
| run: | | |
| python docs/update_gh_pages.py --pages-dir gh-pages-dir | |
| # ── Upload full store as the Pages artifact ──────────────────────── | |
| - uses: actions/configure-pages@v5 | |
| - uses: actions/upload-pages-artifact@v3 | |
| with: | |
| path: gh-pages-dir/ | |
| # ── Deploy to GitHub Pages (OIDC) ────────────────────────────────── | |
| - name: Deploy | |
| id: deploy | |
| uses: actions/deploy-pages@v4 | |
| # ── Persist the updated version store ───────────────────────────── | |
| # Push the merged gh-pages branch back so the next run can check it | |
| # out and see all previously deployed versions. | |
| - name: Persist version store | |
| run: | | |
| LABEL="${{ needs.build.outputs.version-label }}" | |
| COMMIT_SHA="${GITHUB_SHA:0:7}" | |
| cd gh-pages-dir | |
| git add -A | |
| if git diff --cached --quiet; then | |
| echo "Version store unchanged — nothing to push." | |
| else | |
| git commit -m "docs: add ${LABEL} (${COMMIT_SHA})" | |
| git push origin gh-pages | |
| fi |