Build and upload docs independently (#2231)

noonio · web-flow · commit aa34b347c187 · 2025-09-19T10:12:40.000+01:00
Now the docs build only on pushes to each branch, and we rely on the
GitHub Pages Action to upload all the files that are present; i.e. never
remove anything previously uploaded.

Maybe it's worth people having an opinion on how they feel about this;
how would we remove something we uploaded? It'd need to be a manual
intervention now.

&gt; [!Note]
&gt; We switch from using "peaceiris"'s GitHub Action task to JamesIves';
as it seems more up to date.
diff --git a/.github/workflows/publish-docs.yaml b/.github/workflows/publish-docs.yaml
@@ -13,76 +13,71 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: write
-    # if: ${{ github.event.workflow_run.conclusion == 'success' }}
     steps:
 
-    - name: 📥 Checkout repository
-      uses: actions/checkout@v4
-      with:
-        repository: cardano-scaling/hydra
-        ref: release
-        # Also ensure we have all history with all tags
-        fetch-depth: 0
-
     - name: ❄ Setup Nix/Cachix
       uses: ./.github/actions/nix-cachix-setup
       with:
         authToken: '${{ secrets.CACHIX_CARDANO_SCALING_AUTH_TOKEN }}'
 
-    - name: Build stable (i.e. from `release`) documentation
-      working-directory: docs
-      run: |
-        nix build .#docs
-
-        export out=/tmp/public/head-protocol
-        mkdir -p $out
-        cp result/build/* $out -r
+    - name: 📥 Checkout repository
+      uses: actions/checkout@v4
 
-        nix develop .#hydra-node-bench --command -- tx-cost --output-directory $out/benchmarks/
-        nix develop .#hydra-node-bench --command -- micro -o $out/benchmarks/ledger-bench.html
-        nix develop .#hydra-cluster-bench --command -- bench-e2e datasets datasets/1-node.json datasets/3-nodes.json --output-directory $out/benchmarks
+    - name: Build documentation and compute benchmarks
+      run: |
 
-        # Clean the working copy
-        git clean -dxf
+        # Release
+        DERIVATION=docs
+        OUT_PATH=
 
-    - name: Checkout master
-      working-directory: docs
-      run: |
-        git reset origin/master --hard
-        sed -i 's|head-protocol|head-protocol/unstable|' docusaurus.config.js
+        [[ ${{ github.ref_name }} = "master" ]] && \
+          DERIVATION=docs-unstable && \
+          OUT_PATH=/unstable
 
-    - name: Build /unstable documentation
-      working-directory: docs
-      run: |
-        nix build .#docs
+        nix build .#${DERIVATION}
 
-        export out=/tmp/public/head-protocol/unstable
+        export out=/tmp/public/head-protocol${OUT_PATH}
         mkdir -p $out
         cp result/build/* $out -r
 
         nix develop .#hydra-node-bench --command -- tx-cost --output-directory $out/benchmarks/
         nix develop .#hydra-node-bench --command -- micro -o $out/benchmarks/ledger-bench.html
-        nix develop .#hydra-cluster-bench --command -- bench-e2e datasets datasets/1-node.json datasets/3-nodes.json --output-directory $out/benchmarks
-
+        nix develop .#hydra-cluster-bench --command -- \
+          bench-e2e \
+          datasets \
+          hydra-cluster/datasets/1-node.json \
+          hydra-cluster/datasets/3-nodes.json \
+          --output-directory $out/benchmarks
 
     - name: 👉 Create redirects
       run: |
+
         function redirect() {
           echo "Creating redirect: $1 -> $2"
           mkdir -p $(dirname $1)
           echo "<!DOCTYPE html><html><head><meta http-equiv=\"Refresh\" content=\"0; URL=${2}\"></head></html>" > $1
         }
         echo "hydra.family" > /tmp/public/CNAME
+        touch /tmp/public/.nojekyll
+
         redirect /tmp/public/index.html https://hydra.family/head-protocol
+
         # Monthly reports moved to scaling website (2024-02-29)
+
         rm -rf /tmp/public/head-protocol/monthly
+
+        # Note: This runs on pushes to either branch, but it doesn't matter as
+        # it doesn't hurt to write these files twice.
+
         redirect /tmp/public/head-protocol/monthly/index.html https://cardano-scaling.github.io/website/monthly
         redirect /tmp/public/head-protocol/unstable/monthly/index.html https://cardano-scaling.github.io/website/monthly
 
     - name: 🚢 Publish Documentation
-      uses: peaceiris/actions-gh-pages@v4
+      uses: JamesIves/github-pages-deploy-action@v4
       with:
-        github_token: ${{ secrets.GITHUB_TOKEN || github.token }}
-        publish_dir: /tmp/public
-        enable_jekyll: true
-        force_orphan: true
+        token: ${{ secrets.GITHUB_TOKEN || github.token }}
+        folder: /tmp/public
+        # Note: This is crucial! We _never_ remove files that we have
+        # previously uploaded. This might be surprising if we expect something
+        # we previously uploaded to be _removed_!
+        clean: false
diff --git a/nix/hydra/docs.nix b/nix/hydra/docs.nix
@@ -1,34 +1,42 @@
 { self, inputs, ... }: {
   perSystem = { self', pkgs, lib, system, ... }: {
-    packages.docs =
-      let
-        src = pkgs.stdenv.mkDerivation {
-          name = "hydra-docs-source";
-          dontBuild = true;
-          dontUnpack = true;
-          installPhase = ''
-            mkdir -p $out
-            mkdir -p $out/static
-            cp -r ${lib.cleanSource "${self}/docs"}/* $out/
-            cp ${inputs.hydra-spec.packages.${system}.default}/hydra-spec.pdf $out/static
-            cp -r ${self'.packages.haddocks} $out/static/haddocks
+    packages = rec {
+      docs =
+        let
+          src = pkgs.stdenv.mkDerivation {
+            name = "hydra-docs-source";
+            dontBuild = true;
+            dontUnpack = true;
+            installPhase = ''
+              mkdir -p $out
+              mkdir -p $out/static
+              cp -r ${lib.cleanSource "${self}/docs"}/* $out/
+              cp ${inputs.hydra-spec.packages.${system}.default}/hydra-spec.pdf $out/static
+              cp -r ${self'.packages.haddocks} $out/static/haddocks
+            '';
+          };
+
+          gitWrapper = pkgs.writeShellScriptBin "git" ''
+            if [ "$1" = "--no-pager" ] && [ "$2" = "log" ] && [ "$3" = "-1" ] && [ "$4" = "--pretty=format:'%aI'" ]; then
+              date --date="@${builtins.toString self.sourceInfo.lastModified}" +%DT%T
+            elif [ "$1" = "--no-pager" ] && [ "$2" = "log" ] && [ "$3" = "-1" ] && [ "$4" = "--pretty=format:'%H'" ]; then
+              echo "${if (self ? rev) then self.rev else self.sourceInfo.dirtyRev}"
+            else
+              echo "Pure Git Command Not Implemented: $@"
+            fi
           '';
+        in
+        pkgs.buildYarnPackage rec {
+          inherit src;
+          yarnBuildMore = "yarn build";
+          nativeBuildInputs = [ gitWrapper ];
         };
 
-        gitWrapper = pkgs.writeShellScriptBin "git" ''
-          if [ "$1" = "--no-pager" ] && [ "$2" = "log" ] && [ "$3" = "-1" ] && [ "$4" = "--pretty=format:'%aI'" ]; then
-            date --date="@${builtins.toString self.sourceInfo.lastModified}" +%DT%T
-          elif [ "$1" = "--no-pager" ] && [ "$2" = "log" ] && [ "$3" = "-1" ] && [ "$4" = "--pretty=format:'%H'" ]; then
-            echo "${if (self ? rev) then self.rev else self.sourceInfo.dirtyRev}" 
-          else
-            echo "Pure Git Command Not Implemented: $@"
-          fi
+      docs-unstable = docs.overrideAttrs {
+        configurePhase = ''
+          sed -i 's|head-protocol|head-protocol/unstable|' docusaurus.config.js
         '';
-      in
-      pkgs.buildYarnPackage rec {
-        inherit src;
-        yarnBuildMore = "yarn build";
-        nativeBuildInputs = [ gitWrapper ];
       };
+    };
   };
 }
