Align versioned docs with PyPI releases (#47)

.cursor/rules/diataxis-docs.mdc

@@ -37,4 +37,6 @@ This repository's docs follow [Diátaxis](https://diataxis.fr/). Keep them consi
 
 ## Published site
 
-Configured by `mkdocs.yml` (Material). GitHub Pages workflow: `.github/workflows/docs.yml`.
+Configured by `mkdocs.yml` (Material + mike version picker). Changelog: `docs/release-notes.md`.
+
+GitHub Pages is the `gh-pages` branch (mike). The Deploy docs workflow builds on docs PRs and deploys a versioned site only after a successful Publish to PyPI run (`workflow_run`), not on every `master` docs push.

.github/workflows/docs.yml

@@ -1,43 +1,43 @@
 name: Deploy docs
 
-# Test on this PR: the build job runs automatically on pull_request.
-# Test full Pages deploy before merge: Actions → Deploy docs → Run workflow
-# (select this branch). Requires Pages source = GitHub Actions in repo settings.
+# PR / path changes: build-only (mkdocs --strict).
+# Versioned deploy (mike → gh-pages) runs after a successful "Publish to PyPI"
+# workflow, or via workflow_dispatch for manual recovery.
+#
+# One-time repo setting: Pages source = Deploy from a branch → gh-pages / (root).
+
 on:
-  push:
-    branches: [master]
-    paths:
-      - "docs/**"
-      - "docs/assets/**"
-      - "mkdocs.yml"
-      - "requirements-docs.txt"
-      - ".github/workflows/docs.yml"
   pull_request:
     types: [opened, synchronize, reopened, ready_for_review]
     paths:
       - "docs/**"
-      - "docs/assets/**"
       - "mkdocs.yml"
       - "requirements-docs.txt"
       - ".github/workflows/docs.yml"
+  workflow_run:
+    workflows: ["Publish to PyPI"]
+    types: [completed]
   workflow_dispatch:
     inputs:
-      deploy:
-        description: "Upload artifact and deploy to GitHub Pages"
+      version:
+        description: "Docs version to deploy (e.g. 0.7.0, without v prefix)"
+        required: true
+        type: string
+      update_latest:
+        description: "Also update the latest alias and set it as default"
         type: boolean
         default: true
 
 permissions:
   contents: read
-  pages: write
-  id-token: write
 
 concurrency:
-  group: pages
+  group: docs-${{ github.event_name }}-${{ github.ref }}
   cancel-in-progress: false
 
 jobs:
   build:
+    if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -60,24 +60,76 @@ jobs:
       - name: Build site
         run: mkdocs build --strict --clean
 
-      - name: Upload Pages artifact
-        if: >
-          github.event_name == 'push' ||
-          (github.event_name == 'workflow_dispatch' && inputs.deploy)
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: site
-
   deploy:
     if: >
-      github.event_name == 'push' ||
-      (github.event_name == 'workflow_dispatch' && inputs.deploy)
-    needs: build
+      (github.event_name == 'workflow_run' &&
+       github.event.workflow_run.conclusion == 'success') ||
+      github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      contents: write
     steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
+      - name: Checkout master (includes post-publish release notes)
+        uses: actions/checkout@v4
+        with:
+          ref: master
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install docs dependencies
+        run: pip install -r requirements-docs.txt
+
+      - name: Resolve version
+        id: ver
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          DISPATCH_VERSION: ${{ inputs.version }}
+          HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
+          HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
+          UPDATE_LATEST_INPUT: ${{ inputs.update_latest }}
+        run: |
+          set -euo pipefail
+          if [ "$EVENT_NAME" = "workflow_dispatch" ]; then
+            VERSION="${DISPATCH_VERSION#v}"
+            UPDATE_LATEST="${UPDATE_LATEST_INPUT:-true}"
+          else
+            git fetch --tags origin
+            VERSION=""
+            if [[ "${HEAD_BRANCH:-}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+              VERSION="${HEAD_BRANCH#v}"
+            elif [ -n "${HEAD_SHA:-}" ]; then
+              TAG=$(git tag --points-at "$HEAD_SHA" | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1 || true)
+              if [ -n "$TAG" ]; then
+                VERSION="${TAG#v}"
+              fi
+            fi
+            if [ -z "$VERSION" ]; then
+              echo "Could not resolve release version from workflow_run (branch=$HEAD_BRANCH sha=$HEAD_SHA)"
+              exit 1
+            fi
+            UPDATE_LATEST=true
+          fi
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "update_latest=$UPDATE_LATEST" >> "$GITHUB_OUTPUT"
+          echo "Deploying docs version $VERSION (update_latest=$UPDATE_LATEST)"
+
+      - name: Configure git for mike
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Deploy with mike
+        env:
+          VERSION: ${{ steps.ver.outputs.version }}
+          UPDATE_LATEST: ${{ steps.ver.outputs.update_latest }}
+        run: |
+          set -euo pipefail
+          if [ "$UPDATE_LATEST" = "true" ]; then
+            mike deploy --push --update-aliases "$VERSION" latest
+            mike set-default --push latest
+          else
+            mike deploy --push "$VERSION"
+          fi

.github/workflows/publish.yml

@@ -1,12 +1,31 @@
 name: Publish to PyPI
 
+# Releasing
+# ---------
+# 1. Bump `__version__` in tapsdk/__version__.py.
+#    Optionally pre-write the matching section in docs/release-notes.md
+#    (if omitted, this workflow inserts one from PRs merged into master).
+# 2. Merge the release commit into master.
+# 3. Create and push an annotated tag matching the package version:
+#
+#      git tag -a v0.7.0 -m "Release 0.7.0"
+#      git push origin v0.7.0
+#
+# This workflow runs lint/tests, ensures release notes, builds the sdist/wheel,
+# and uploads to PyPI via Trusted Publishing. Versioned docs deploy separately
+# in "Deploy docs" after this workflow succeeds (so a docs failure cannot fail
+# the PyPI publish).
+#
+# Maintainers must configure PyPI Trusted Publishing for project tap-python-sdk,
+# repository TapWithUs/tap-python-sdk, and a GitHub `pypi` environment.
+
 on:
   push:
     tags:
       - "v*"
 
 permissions:
-  contents: read
+  contents: write
   id-token: write
 
 jobs:
@@ -17,9 +36,9 @@ jobs:
         os: [ubuntu-latest, windows-latest, macos-latest]
         python-version: ["3.9", "3.10", "3.11"]
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
@@ -38,11 +57,15 @@ jobs:
     runs-on: ubuntu-latest
     environment: pypi
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "3.11"
+
       - name: Validate tag version matches package version
         run: |
           TAG="${GITHUB_REF_NAME#v}"
@@ -52,28 +75,63 @@ jobs:
             exit 1
           fi
           echo "Version validated: $PACKAGE_VERSION"
+
+      - name: Ensure release notes section
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+          GITHUB_SHA: ${{ github.sha }}
+        run: python scripts/update_release_notes_from_prs.py
+
       - name: Install build dependencies
         run: |
           python -m pip install --upgrade pip
           pip install build
+
       - name: Build package
         run: python -m build
+
       - name: Check package metadata
         run: |
           pip install twine
           twine check dist/*
+
       # Import package/version only — avoid TapSDK/bleak, which needs bluetoothctl on Linux.
       - name: Smoke test built wheel
         run: |
           python -m venv /tmp/wheel-venv
           /tmp/wheel-venv/bin/pip install --upgrade pip
           /tmp/wheel-venv/bin/pip install dist/*.whl
           /tmp/wheel-venv/bin/python -c "import tapsdk; from tapsdk.__version__ import __version__; print(__version__)"
+
       - name: Smoke test built sdist
         run: |
           python -m venv /tmp/sdist-venv
           /tmp/sdist-venv/bin/pip install --upgrade pip
           /tmp/sdist-venv/bin/pip install dist/*.tar.gz
           /tmp/sdist-venv/bin/python -c "import tapsdk; from tapsdk.__version__ import __version__; print(__version__)"
+
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Commit release notes to master if changed
+        run: |
+          set -euo pipefail
+          if git diff --quiet -- docs/release-notes.md; then
+            echo "No release notes changes to commit"
+            exit 0
+          fi
+          VERSION="${GITHUB_REF_NAME#v}"
+          cp docs/release-notes.md /tmp/release-notes.md
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git fetch origin master
+          git checkout -B _release_notes origin/master
+          cp /tmp/release-notes.md docs/release-notes.md
+          git add docs/release-notes.md
+          if git diff --cached --quiet; then
+            echo "master already has the updated release notes"
+            exit 0
+          fi
+          git commit -m "docs: add release notes for ${VERSION}"
+          git push origin HEAD:master

MANIFEST.in

@@ -1,6 +1,6 @@
-include History.md
 include LICENSE
 include Readme.md
+include docs/release-notes.md
 
 recursive-include tests *
 recursive-exclude * __pycache__

Readme.md

@@ -8,7 +8,7 @@ BLE SDK for building Python apps that connect to **Tap Strap** and **TapXR**, se
 
 ### Documentation
 
-Published docs (MkDocs Material): [https://tapwithus.github.io/tap-python-sdk/](https://tapwithus.github.io/tap-python-sdk/)
+Published docs (MkDocs Material, versioned with mike): [https://tapwithus.github.io/tap-python-sdk/](https://tapwithus.github.io/tap-python-sdk/)
 
 Pick the path that matches your goal:
 
@@ -18,6 +18,7 @@ Pick the path that matches your goal:
 | Solve a specific task | [How-to guides](docs/how-to/index.md) |
 | Look up APIs and types | [Reference](docs/reference/index.md) |
 | Understand modes and sensors | [Explanation](docs/explanation/index.md) |
+| Read the changelog | [Release notes](docs/release-notes.md) |
 
 Full index: [docs/index.md](docs/index.md). Local preview: `pip install -r requirements-docs.txt && mkdocs serve`.
 
@@ -56,7 +57,11 @@ Pair the Tap with the OS first. Update firmware with Tap Manager. More complete
 
 ### Migrating from 0.6.x
 
-Breaking API changes are listed in [Migrate from 0.6](docs/how-to/migrate-from-0.6.md) and [History.md](History.md).
+Breaking API changes are listed in [Migrate from 0.6](docs/how-to/migrate-from-0.6.md) and [Release notes](docs/release-notes.md).
+
+### Releasing
+
+PyPI releases publish on annotated `v*` tags. Docs deploy separately after a successful publish. See the header comments in [`.github/workflows/publish.yml`](.github/workflows/publish.yml).
 
 ### Testing
 

docs/index.md

@@ -8,6 +8,7 @@ Pick the section that matches what you need:
 | Solve a specific task | [How-to guides](how-to/index.md) |
 | Look up an API, type, or event | [Reference](reference/index.md) |
 | Understand how modes and sensors work | [Explanation](explanation/index.md) |
+| Read the changelog for a PyPI release | [Release notes](release-notes.md) |
 
 ## Package
 

History.md → docs/release-notes.md

@@ -1,21 +1,6 @@
-# History
+# Release notes
 
-## Releasing
-
-PyPI releases are published automatically when a version tag is pushed to GitHub.
-
-1. Bump `__version__` in `tapsdk/__version__.py` and update this file.
-2. Merge the release changes into `develop`, then into `master` as needed.
-3. Create and push an annotated tag whose name matches the package version (for example `v0.7.0`):
-
-   ```bash
-   git tag -a v0.7.0 -m "Release 0.7.0"
-   git push origin v0.7.0
-   ```
-
-The `Publish to PyPI` workflow runs the same lint and test matrix as CI, verifies that the tag (without the `v` prefix) matches `tapsdk.__version__`, builds the package with `python -m build`, and uploads it to PyPI using Trusted Publishing.
-
-Maintainers must configure PyPI Trusted Publishing for the `tap-python-sdk` project name, the `TapWithUs/tap-python-sdk` repository, and a GitHub `pypi` environment before the first automated release.
+Changelog for published `tap-python-sdk` releases on PyPI.
 
 ## 0.7.0 (2026-06-09)
 ______________________
@@ -84,4 +69,3 @@ ______________________
 ### Main features
 
 * SDK created.
-

mkdocs.yml

@@ -41,6 +41,15 @@ theme:
 plugins:
   - search
 
+extra:
+  version:
+    provider: mike
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/TapWithUs/tap-python-sdk
+    - icon: fontawesome/brands/python
+      link: https://pypi.org/project/tap-python-sdk/
+
 markdown_extensions:
   - admonition
   - attr_list
@@ -82,10 +91,4 @@ nav:
       - Connection model: explanation/connection-model.md
       - Input modes: explanation/input-modes.md
       - Raw sensors: explanation/raw-sensors.md
-
-extra:
-  social:
-    - icon: fontawesome/brands/github
-      link: https://github.com/TapWithUs/tap-python-sdk
-    - icon: fontawesome/brands/python
-      link: https://pypi.org/project/tap-python-sdk/
+  - Release notes: release-notes.md

requirements-docs.txt

@@ -1,2 +1,3 @@
 mkdocs>=1.6,<2
 mkdocs-material>=9.5,<10
+mike>=2.1,<3