github/update: sync with main

.github/workflows/build_documentation.yml

@@ -2,8 +2,10 @@ name: Build and deploy documentation
 
 on:
   push:
-    # Runs on pushes targeting the default branch
-    branches: [main]
+    # Runs on pushes targeting the release branches
+    branches:
+      - main
+      - nixos-24.05
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
@@ -26,13 +28,13 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     timeout-minutes: 40
+
+    env:
+      repo: ${{ github.repository }}
+      repoName: ${{ github.event.repository.name }}
+      out: docs-build
+
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup pages
-        uses: actions/configure-pages@v5
-
       - name: Install nix
         uses: cachix/install-nix-action@v26
         with:
@@ -42,9 +44,51 @@ jobs:
         uses: cachix/cachix-action@v15
         with:
           name: nix-community
-          authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'
+          authToken: "${{ secrets.CACHIX_AUTH_TOKEN }}"
 
-      - run: ./build-docs.sh
+      - name: Build docs
+        run: |
+          set -ex
+
+          # 1: branch
+          # 2: install dir (relative to /nixvim/)
+          build() {
+            branch="$1"
+            dir="${2:+/$2}"
+            flakeref="github:${repo}${branch:+/$branch}"
+            baseHref="/${repoName}${dir}/"
+            installDir="${out}${dir}"
+
+            # Build docs for the given flake ref, overriding baseHref in the derivation args
+            nix build --impure \
+                --argstr flakeref "$flakeref" \
+                --argstr baseHref "$baseHref" \
+                --expr '
+                  {
+                    flakeref,
+                    baseHref,
+                    system ? builtins.currentSystem,
+                  }:
+                  let
+                    flake = builtins.getFlake flakeref;
+                    packages = flake.outputs.packages.${system};
+                  in
+                  packages.docs.override {
+                    inherit baseHref;
+                  }
+                '
+
+            # Copy the result to the install dir
+            mkdir -p "$installDir"
+            cp -r result/share/doc/* "$installDir"
+          }
+
+          # Install main-branch docs at the top-level
+          build 'main' ''
+
+          # Install 24.05 docs under 'stable'
+          # TODO: consider having `<release>` instead of `stable`
+          build 'nixos-24.05' 'stable'
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3