Merge pull request #225 from expipiplus1/combined-docs

Add nix expression to generate combined documentation

.github/workflows/ci.yml

@@ -273,6 +273,7 @@ jobs:
     - run: nix-build nix/release.nix
     - run: nix-build nix/release.nix -A docs
     - run: nix-build nix/release.nix -A sdistTest
+    - run: nix-build nix/release.nix -A docs-combined
 
   shellcheck:
     runs-on: ubuntu-20.04

nix/release.nix

@@ -1,32 +1,107 @@
 { pkgs ? import ./nixpkgs.nix, compiler ? "ghc884" }:
+# Use old GHC until
+# https://github.com/haskell-infra/hackage-trustees/issues/276 is fixed
 
 with pkgs.haskell.lib;
+with pkgs.lib;
 
 let
+  #
+  # Utils
+  #
+
+  haskellPackages = let
+    hp = if compiler == null then
+      pkgs.haskellPackages
+    else
+      pkgs.haskell.packages.${compiler};
+  in hp.override {
+    overrides = import ./haskell-packages.nix {
+      inherit pkgs;
+      hoogle = false;
+    };
+  };
+
+  haddockInterface = pkg:
+    overrideDerivation pkg (drv: {
+      name = "${drv.name}-haddock-interface";
+      # Disable the "doc" output here.
+      outputs = [ "out" ];
+      buildPhase = ''
+        ./Setup haddock --haddock-options="--dump-interface=haddock-interface"
+      '';
+      haddockPhase = ":";
+      checkPhase = ":";
+      installPhase = ''
+        mkdir -p "$out"
+        mv haddock-interface "$out/"
+      '';
+    });
+
+  #
+  # Generate a
+  #
+  combineDocs = ps:
+    pkgs.runCommandNoCC "docs-combined" {
+      nativeBuildInputs = with pkgs; [ fd haskellPackages.ghc ];
+    } ''
+      for p in ${
+        concatStringsSep " "
+        (map (p: "${documentationTarball p}/${p.name}-docs.tar.gz") ps)
+      }; do
+        tar xzv < "$p"
+      done;
+
+      remote=https://hackage.haskell.org/package/
+
+      printf "Making any links to local packages relative\n"
+      fd 'html$' --type f --exec \
+        sed -E -i 's|<a href="/package/(${
+          concatStringsSep "\\|" (map (p: "${p.pname}-${p.version}") ps)
+        })/docs|<a href="../\1-docs|g'
+
+      printf "Replacing all absolute links to point to Hackage\n"
+      fd 'html$' --type f --exec \
+        sed -i 's|<a href="/package/|<a href="'$remote'|g'
+
+      haddock \
+        --quickjump \
+        --gen-contents \
+        --gen-index \
+        ${
+          concatMapStringsSep " " (s:
+            "--read-interface=${s.name}-docs,${
+              haddockInterface s
+            }/haddock-interface") ps
+        }
+
+      mkdir -p "$out"
+      mv * "$out/"
+      rm "$out/env-vars"
+    '';
+
+  #
+  # Interesting stuff
+  #
+
   vulkanPkgs = import ../default.nix {
     inherit pkgs compiler;
     hoogle = false;
     forShell = false;
   };
 
-  docDrv = _name: drv:
-    (overrideCabal drv (drv: {
-      doHaddock = true;
-      haddockFlags = [ "--for-hackage" ];
-      postHaddock = ''
-        mkdir -p "$doc"
-        tar --format=ustar -czf "$doc/${drv.pname}-${drv.version}-docs.tar.gz" -C dist/doc/html "${drv.pname}-${drv.version}-docs"
-      '';
-    })).doc;
+  docDrv = _name: documentationTarball;
 
   tarballDrv = _name: sdistTarball;
 
   sdistTestDrv = _name: buildFromSdist;
 
-in with pkgs.lib;
-mapAttrs tarballDrv vulkanPkgs // {
-  docs = mapAttrs docDrv
-    (filterAttrs (n: _: n != "generate-new" && n != "vulkan-examples")
-      vulkanPkgs);
+  docPackages =
+    filterAttrs (n: _: n != "generate-new" && n != "vulkan-examples")
+    vulkanPkgs;
+
+in mapAttrs tarballDrv vulkanPkgs // {
   sdistTest = mapAttrs sdistTestDrv vulkanPkgs;
+  docs = mapAttrs docDrv docPackages;
+  docs-combined = combineDocs (attrValues docPackages);
 }

release-checklist.md

@@ -50,15 +50,11 @@ This is done automatically on merge to the main branch
 
 ## gh-pages documentation
 
-- Run `./scripts/gen-standalone-haddocks.sh` script pointing to a worktree on the gh-pages branch
-  - Make sure to clean that directory first
-
 (on my machine)
 
 ```bash
 rm -rf ../vulkan-docs/*
-nix-shell stack ghc
-./scripts/gen-standalone-haddocks.sh ../vulkan-docs
+cp -r $(nix-build --no-link nix/release.nix -A docs-combined)/* ../vulkan-docs
 cd ../vulkan-docs
 git add .
 git commit -m 'vXXX'