refactor: pages.yaml

* Add pre-commit linting and validation
* Auto-generate the strategy matrix
* Move Bazelisk and mdBook versions to `env` so that it's easier to
  test and upgrade to new versions.
* `fail-fast: false` so that when one of the matrix jobs fails so that
  we can see failures for all of the jobs (easier to debug and the jobs
  are lightweight so it's not too costly).
* Simplify the patching of old branches
* Make steps easier to read, shortening lines and adding whitespace

.github/workflows/pages.yaml

@@ -1,4 +1,5 @@
 name: Generate docs
+
 on:
   pull_request:
     branches:
@@ -9,111 +10,187 @@ on:
   push:
     branches:
       - main
+
+env:
+  BAZELISK_VERSION: 1.23.0
+  MDBOOK_VERSION: 0.4.42
+
+  GH_REPO: ${{ github.repository }}
+  MIN_VERSION: ${{ github.event.inputs.MIN_VERSION || '0.1.0' }}
+  FILTER_VERSION: ${{ github.event.inputs.FILTER_VERSION || '' }}
+  RELEASE_TAG_REGEX: ^\d+\.\d+\.\d+$
+
 jobs:
-  pages:
+  setup:
     runs-on: ubuntu-latest
-    strategy:
+
-      matrix:
+    defaults:
-        # Create a job for release
+      run:
-        include:
+        shell: bash --noprofile --norc -euo pipefail {0}
-          - ref: main
+
-          - ref: "0.12.0"
-          - ref: "0.11.1"
-          - ref: "0.11.0"
-          - ref: "0.10.1"
-          - ref: "0.9.0"
-          - ref: "0.8.0"
-          - ref: "0.7.1"
-          - ref: "0.7.0"
-          - ref: "0.6.0"
-          - ref: "0.5.1"
-          - ref: "0.5.0"
-          - ref: "0.4.0"
-          - ref: "0.3.0"
-          - ref: "0.2.0"
-          - ref: "0.1.0"
     steps:
-      - uses: actions/checkout@v2
+      - name: get release tags that match $release_tag_regex
-        if: ${{ matrix.ref == 'main' }}
+        id: get_release_tags
-      - uses: actions/checkout@v2
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          RELEASES_JSON="$(
+            curl -s --fail-with-body \
+              -H "Authorization: token $GH_TOKEN" \
+              "https://api.github.com/repos/$GH_REPO/tags"
+          )"
+
+          RELEASES_JSON_FILTERED="$(echo "$RELEASES_JSON" |
+            jq -c \
+              --arg RELEASE_TAG_REGEX "$RELEASE_TAG_REGEX" \
+              --arg FILTER_VERSION "$FILTER_VERSION" \
+              --arg MIN_VERSION "$MIN_VERSION" '
+              [ "main" ] +
+              ([.[].name |
+                 select(
+                   (test($RELEASE_TAG_REGEX) and
+                    (. | split(".") | map(tonumber) >= ($MIN_VERSION | split(".") | map(tonumber)))
+                   ) and ($FILTER_VERSION == "" or . == $FILTER_VERSION)
+                 )
+              ])
+              '
+          )"
+          echo "releases=$RELEASES_JSON_FILTERED"
+          echo "releases=$RELEASES_JSON_FILTERED" >> "$GITHUB_OUTPUT"
+
+    outputs:
+      releases: ${{ steps.get_release_tags.outputs.releases || '[]' }}
+
+  build:
+    runs-on: ubuntu-latest
+    needs: setup
+
+    defaults:
+      run:
+        shell: bash --noprofile --norc -euo pipefail {0}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ref: ${{ fromJson(needs.setup.outputs.releases) }}
+
+    env:
+      WORKSPACE: ${{ github.workspace }}
+      BIN: ${{ github.workspace }}/bin
+
+    steps:
+      - name: Checkout $REF
+        uses: actions/checkout@v4
         with:
           ref: ${{ matrix.ref }}
-        if: ${{ matrix.ref != 'main' }}
+
-      - name: Pin the release to main
+      - name: Patch $REF
-        run: echo "RELEASE=main" >> $GITHUB_ENV
+        env:
-        if: ${{ matrix.ref == 'main' }}
+          REF: ${{ matrix.ref }}
-      - name: Patch older branches
         run: |
-          ref="${{ matrix.ref }}"
+          [[ "$REF" == "main" ]] && exit
 
-          [[ "$ref" == "main" ]] && exit
+          PATCH=".github/docs-${REF}.patch"
 
-          v_major="$(echo "$ref" | cut -d. -f1)"
+          URL="https://raw.githubusercontent.com/$GH_REPO/main/$PATCH"
-          v_minor="$(echo "$ref" | cut -d. -f2)"
+          echo "$URL"
-          v_patch="$(echo "$ref" | cut -d. -f3)"
 
-          [[ $v_minor -gt 10 ]] && exit
+          curl -LO --fail-with-body "$URL" || {
+              echo "No patch found for $REF, exiting..."
+              exit 0
+          }
+
+          echo "Patching ref: $REF"
+          git apply "$(basename "$PATCH")"
 
-          mkdir -p ${{ github.workspace }}/.github
-          curl https://raw.githubusercontent.com/bazel-contrib/rules_foreign_cc/main/.github/docs-${{ matrix.ref }}.patch > ${{ github.workspace }}/.github/docs-${{ matrix.ref }}.patch
-          git apply ${{ github.workspace }}/.github/docs-${{ matrix.ref }}.patch
       - name: Install bazelisk
         run: |
-          curl -LO "https://github.com/bazelbuild/bazelisk/releases/download/v1.9.0/bazelisk-linux-amd64"
+          BAZELISK="bazelisk-linux-amd64"
-          mkdir -p "${{ github.workspace }}/bin/"
+
-          mv bazelisk-linux-amd64 "${{ github.workspace }}/bin/bazel"
+          URL="https://github.com/bazelbuild/bazelisk/releases/download/v$BAZELISK_VERSION/$BAZELISK"
-          chmod +x "${{ github.workspace }}/bin/bazel"
+          echo "URL=$URL"
-      - name: Generate docs
+          curl -LO --fail-with-body "$URL"
-        run: |
+
-          "${{ github.workspace }}/bin/bazel" run //:generate_docs
+          chmod +x "$BAZELISK"
-          "${{ github.workspace }}/bin/bazel" clean
+
-        working-directory: ${{ github.workspace }}/docs
+          mkdir -p "$BIN"
+          mv "$BAZELISK" "$BIN/bazel"
+
       - name: Install mdbook
         run: |
-          curl -LO "https://github.com/rust-lang/mdBook/releases/download/v0.4.10/mdbook-v0.4.10-x86_64-unknown-linux-gnu.tar.gz"
+          MDBOOK="mdbook-v$MDBOOK_VERSION-x86_64-unknown-linux-gnu.tar.gz"
-          mkdir -p "${{ github.workspace }}/bin/"
+
-          tar -xvf mdbook-v0.4.10-x86_64-unknown-linux-gnu.tar.gz
+          URL="https://github.com/rust-lang/mdBook/releases/download/v$MDBOOK_VERSION/$MDBOOK"
-          mv mdbook "${{ github.workspace }}/bin/mdbook"
+          echo "URL=$URL"
-          chmod +x "${{ github.workspace }}/bin/mdbook"
+          curl -LO --fail-with-body "$URL"
-      - name: mdbook build
+
-        run: ${{ github.workspace }}/bin/mdbook build
+          tar -xvf "$MDBOOK"
+          chmod +x mdbook
+
+          mkdir -p "$BIN"
+          mv mdbook "$BIN/mdbook"
+
+      - name: bazel run //:generate_docs
+        run: |
+          "$BIN/bazel" run //:generate_docs
         working-directory: ${{ github.workspace }}/docs
-      - name: Save the newly built book
+
+      - name: mdbook build root
+        run: |
+          "$BIN/mdbook" build
+        working-directory: ${{ github.workspace }}/docs/root
+        if: ${{ matrix.ref == 'main' }}
+
+      - name: mdbook build docs
+        run: |
+          "$BIN/mdbook" build
+        working-directory: ${{ github.workspace }}/docs
+
+      - name: Upload docs root
         uses: actions/upload-artifact@v4
         with:
-          name: "${{ matrix.ref }}"
+          name: ${{ matrix.ref }}-root
+          path: ${{ github.workspace }}/docs/root/book
+          if-no-files-found: error
+        if: ${{ github.event_name != 'pull_request' && matrix.ref == 'main' }}
+
+      - name: Upload docs/book
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.ref }}
           path: ${{ github.workspace }}/docs/book
           if-no-files-found: error
         if: ${{ github.event_name != 'pull_request' }}
-      - name: Build root
+
-        run: ${{ github.workspace }}/bin/mdbook build
+  deploy:
-        if: ${{ matrix.ref == 'main' }}
-        working-directory: ${{ github.workspace }}/docs/root
-      - name: Save the newly built book
-        uses: actions/upload-artifact@v4
-        with:
-          name: "${{ matrix.ref }}-root"
-          path: ${{ github.workspace }}/docs/root/book
-          if-no-files-found: error
-        if: ${{ matrix.ref == 'main' && github.event_name != 'pull_request' }}
-  publish:
-    needs: pages
-    if: ${{ github.event_name != 'pull_request' }}
     runs-on: ubuntu-latest
+    needs: build
+    if: ${{ github.event_name != 'pull_request' }}
+
+    defaults:
+      run:
+        shell: bash --noprofile --norc -euo pipefail {0}
+
+    env:
+      WORKSPACE: ${{ github.workspace }}
+
     steps:
-    - name: Fetch artifacts (first root then others so the ordering is correct)
+      - name: Fetch artifacts (first root)
-      uses: actions/download-artifact@v2
+        uses: actions/download-artifact@v4
         with:
           name: main-root
           path: ${{ github.workspace }}/docs/book
-    - name: Fetch artifacts (first root then others so the ordering is correct)
+
-      uses: actions/download-artifact@v2
+      - name: Fetch artifacts (then others)
+        uses: actions/download-artifact@v4
         with:
           path: ${{ github.workspace }}/docs/pages
+
       - name: Install pages
-      run: mv ${{ github.workspace }}/docs/pages/* ${{ github.workspace }}/docs/book/
+        run: mv "$WORKSPACE/docs/pages/"* "$WORKSPACE/docs/book/"
+
       - name: publish
-      uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_branch: docs

.pre-commit-config.yaml

@@ -2,6 +2,11 @@
 # See https://pre-commit.com for more information
 # See https://pre-commit.com/hooks.html for more hooks
 repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-yaml
+
   - repo: https://github.com/keith/pre-commit-buildifier
     rev: 6.1.0.1
     hooks:
@@ -11,3 +16,21 @@ repos:
           - --warnings=all
       - id: buildifier-lint
         args: *args
+
+  - repo: https://github.com/mpalmer/action-validator
+    rev: v0.6.0
+    hooks:
+      - id: action-validator
+        files: >-
+          (?x)^(
+            .github/workflows/pages.yaml
+          )$
+
+  - repo: https://github.com/rhysd/actionlint
+    rev: v1.7.4
+    hooks:
+      - id: actionlint
+        files: >-
+          (?x)^(
+            .github/workflows/pages.yaml
+          )$