Add GitHub Action to rebuild all documentation versions

.github/workflows/docs-rebuild.yaml

@@ -0,0 +1,126 @@
+name: Rebuild documentation
+
+on:
+  workflow_dispatch:
+    inputs:
+      include_dev:
+        description: Publish current master as the moving dev docs version
+        required: true
+        default: true
+        type: boolean
+      continue_on_failed_tags:
+        description: Ignore failed tags and publish successfully rebuilt docs
+        required: true
+        default: true
+        type: boolean
+
+permissions: {}
+
+concurrency:
+  # Versioned docs update the same Git branch and Pages deployment, so publish
+  # jobs must run one at a time. Do not cancel queued release-tag deploys.
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  rebuild:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      # `mike` stores the complete versioned site on `gh-pages`.
+      contents: write
+      # GitHub Pages still publishes from this workflow's uploaded artifact.
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    env:
+      DOCS_DEPLOY_BRANCH: docs-rebuild
+      INCLUDE_DEV: ${{ inputs.include_dev }}
+      CONTINUE_ON_FAILED_TAGS: ${{ inputs.continue_on_failed_tags }}
+    steps:
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          ref: master
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
+        with:
+          python-version: '3.14'
+      - name: Install documentation dependencies
+        run: make docs-install
+      - name: Configure git identity
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - name: Rebuild documentation versions
+        run: |
+          git fetch --force --tags origin 'refs/tags/v*:refs/tags/v*'
+
+          empty_tree="$(git mktree </dev/null)"
+          rebuild_commit="$(git commit-tree "$empty_tree" -m "Rebuild documentation")"
+          git update-ref "refs/heads/$DOCS_DEPLOY_BRANCH" "$rebuild_commit"
+
+          mapfile -t release_tags < <(git tag --list 'v*' --sort=version:refname)
+          failed_tags=()
+          latest_successful_version=
+
+          if [ "${#release_tags[@]}" -gt 0 ]; then
+            for tag in "${release_tags[@]}"; do
+              version="${tag#v}"
+
+              # Use the current checkout's Makefile; GIT_REF selects the old
+              # source tree to render, even if that tag predates docs-deploy.
+              if make docs-deploy VERSION="$version" GIT_REF="$tag"; then
+                latest_successful_version="$version"
+              else
+                if [ "$CONTINUE_ON_FAILED_TAGS" != "true" ]; then
+                  exit 1
+                fi
+
+                failed_tags+=("$tag")
+              fi
+            done
+
+            if [ "${#failed_tags[@]}" -gt 0 ]; then
+              printf 'Skipped documentation tags:\n'
+              printf '  %s\n' "${failed_tags[@]}"
+            fi
+
+            if [ -n "$latest_successful_version" ]; then
+              mike alias \
+                --update-aliases \
+                --alias-type=copy \
+                --remote origin \
+                --branch "$DOCS_DEPLOY_BRANCH" \
+                "$latest_successful_version" \
+                latest
+              make docs-set-default DEFAULT_VERSION=latest
+            fi
+          fi
+
+          if [ "$INCLUDE_DEV" = "true" ]; then
+            git checkout --detach origin/master
+            make docs-deploy VERSION=dev
+          fi
+
+          make docs-export
+        env:
+          # Fetch through git without writing the token into .git/config.
+          GIT_CONFIG_COUNT: 1
+          GIT_CONFIG_KEY_0: http.https://github.com/.extraheader
+          GIT_CONFIG_VALUE_0: "AUTHORIZATION: bearer ${{ github.token }}"
+      - name: Push rebuilt documentation branch
+        run: git push --force origin "refs/heads/$DOCS_DEPLOY_BRANCH:refs/heads/gh-pages"
+        env:
+          # Push through git without writing the token into .git/config.
+          GIT_CONFIG_COUNT: 1
+          GIT_CONFIG_KEY_0: http.https://github.com/.extraheader
+          GIT_CONFIG_VALUE_0: "AUTHORIZATION: bearer ${{ github.token }}"
+      - uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1
+        with:
+          path: site-versioned
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

CONTRIBUTING.md

@@ -16,6 +16,8 @@ Want to contribute to PyLD? Great! Here are a few notes:
 
 ## Documentation
 
+### Building and serving docs
+
 The public documentation site is built with MkDocs Material.
 
 * Install documentation dependencies:
@@ -30,7 +32,9 @@ The public documentation site is built with MkDocs Material.
 
   * `make docs-serve` (override port with `PORT=8008 make docs-serve`)
 
-* Deploy a version of the documentation (with
+### Versioning docs
+
+Deploy a version of the documentation (with
   [mike](https://github.com/jimporter/mike)):
 
   * `VERSION=3.2 ALIASES=latest PUSH=1 make docs-deploy`
@@ -47,6 +51,26 @@ documentation version. Pushing a `v*` release tag publishes that release
 version, updates the `latest` docs alias, and keeps `latest` as the default
 documentation version.
 
+### Rebuilding the documentation
+
+Use the manual "Rebuild documentation" GitHub Actions workflow to rebuild the
+full documentation site from scratch. It rebuilds every `v*` release tag into a
+versioned docs entry, marks the newest release as `latest`, sets `latest` as
+the default version, optionally rebuilds current `master` as `dev`, then
+replaces the `gh-pages` docs store and deploys the rebuilt Pages artifact. This
+is useful when older release docs need to be generated retroactively or when
+the rendered docs store needs to be recreated. 
+
+The workflow uses the current
+`master` Makefile for the rebuild and passes each older tag through `GIT_REF`,
+so the historical tags do not need to contain the `docs-deploy` target.
+Enable the workflow's `continue_on_failed_tags` option to try every release tag
+and print a summary of tags whose docs failed to build; successful docs are
+still published, and `latest` points to the newest release tag that rebuilt
+successfully.
+
+### Bundled JSON-LD contexts
+
 * Refresh bundled JSON-LD context files:
 
   * `make download-bundled-contexts`