feat(nix): build all docs

cryspen · Jan 14, 2025 · 72fc6c1 · 72fc6c1
1 parent f60dee4
commit 72fc6c1
Show file tree

Hide file tree

Showing 9 changed files with 144 additions and 3,978 deletions.
diff --git a/.github/workflows/gh_pages.yml b/.github/workflows/gh_pages.yml
@@ -5,26 +5,36 @@ on:
   push:
     branches: [main]
 
-permissions:
-  contents: write
 jobs:
-  deploy:
+  # Build job
+  build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - name: Configure Git Credentials
-        run: |
-          git config user.name github-actions[bot]
-          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
-      - uses: actions/setup-python@v5
-        with:
-          python-version: 3.x
-      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
-      - uses: actions/cache@v4
+      - uses: actions/checkout@v3
+      - uses: DeterminateSystems/nix-installer-action@main
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+      - name: Build documentation
+        run: nix build .#docs
+      - name: Upload static files as artifact
+        id: deployment
+        uses: actions/upload-pages-artifact@v3
         with:
-          key: mkdocs-material-${{ env.cache_id }}
-          path: .cache
-          restore-keys: |
-            mkdocs-material-
-      - run: pip install mkdocs-material mkdocs-nav-weight mkdocs-glightbox
-      - run: mkdocs gh-deploy --force
+          path: result/
+  # Deploy job
+  deploy:
+    needs: build
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    # Specify runner + deployment step
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4 # or specific "vX.X.X" version tag for this action
diff --git a/cli/default.nix b/cli/default.nix
@@ -1,45 +1,31 @@
-{
-  craneLib,
-  stdenv,
-  makeWrapper,
-  lib,
-  rustc,
-  gcc,
-  hax-engine,
-  doCheck ? true,
-}: let
+{ craneLib, stdenv, makeWrapper, lib, rustc, rustc-docs, gcc, hax-engine
+, doCheck ? true, libz, libiconv }:
+let
   pname = "hax";
-  is-webapp-static-asset = path: builtins.match ".*(script[.]js|index[.]html)" path != null;
-  commonArgs =
-    {
-      version = "0.0.1";
-      src = lib.cleanSourceWith {
-        src = craneLib.path ./..;
-        filter = path: type:
-          builtins.isNull (builtins.match ".*/tests/.*" path)
-          && (craneLib.filterCargoSources path type || is-webapp-static-asset path);
-      };
-      inherit doCheck;
-    }
-    // (
-      if doCheck
-      then {
-        # [cargo test] builds independent workspaces. Each time another
-        # workspace is added, it's corresponding lockfile should be added
-        # in the [cargoLockList] list below.
-        cargoVendorDir = craneLib.vendorMultipleCargoDeps {
-          cargoLockList = [
-            ../Cargo.lock
-            ../tests/Cargo.lock
-          ];
-        };
-      }
-      else {}
-    );
-  cargoArtifacts = craneLib.buildDepsOnly (commonArgs
-    // {
-      pname = pname;
-    });
+  is-webapp-static-asset = path:
+    builtins.match ".*(script[.]js|index[.]html)" path != null;
+  buildInputs = lib.optionals stdenv.isDarwin [ libiconv libz.dev ];
+  binaries = [ hax hax-engine.bin rustc gcc ] ++ buildInputs;
+  commonArgs = {
+    version = "0.0.1";
+    src = lib.cleanSourceWith {
+      src = craneLib.path ./..;
+      filter = path: type:
+        builtins.isNull (builtins.match ".*/tests/.*" path)
+        && (craneLib.filterCargoSources path type
+          || is-webapp-static-asset path);
+    };
+    inherit buildInputs doCheck;
+  } // (if doCheck then {
+    # [cargo test] builds independent workspaces. Each time another
+    # workspace is added, it's corresponding lockfile should be added
+    # in the [cargoLockList] list below.
+    cargoVendorDir = craneLib.vendorMultipleCargoDeps {
+      cargoLockList = [ ../Cargo.lock ../tests/Cargo.lock ];
+    };
+  } else
+    { });
+  cargoArtifacts = craneLib.buildDepsOnly (commonArgs // { pname = pname; });
   hax = stdenv.mkDerivation {
     name = hax_with_artifacts.name;
     unpackPhase = "true";
@@ -49,95 +35,60 @@
       cp -r ${hax_with_artifacts}/bin $out/bin
     '';
   };
-  hax_with_artifacts = craneLib.buildPackage (
-    commonArgs
-    // {
-      inherit cargoArtifacts pname;
-      doInstallCargoArtifacts = true;
-    }
-  );
-  frontend-docs = craneLib.cargoDoc (commonArgs // {
-    preBuildPhases = ["addRustcDocs"];
+  hax_with_artifacts = craneLib.buildPackage (commonArgs // {
+    inherit cargoArtifacts pname;
+    doInstallCargoArtifacts = true;
+  });
+  docs = craneLib.cargoDoc (commonArgs // {
+    # preBuildPhases = [ "addRustcDocs" ];
     cargoDocExtraArgs = "--document-private-items";
-    addRustcDocs = ''
-      mkdir -p target/doc
-      cp --no-preserve=mode -rf ${rustc.passthru.availableComponents.rustc-docs}/share/doc/rust/html/rustc/* target/doc/
-    '';
+    # addRustcDocs = ''
+    #   mkdir -p target/doc
+    #   cp --no-preserve=mode -rf ${rustc-docs}/share/doc/rust/html/rustc/* target/doc/
+    # '';
     inherit cargoArtifacts pname;
   });
-  docs = stdenv.mkDerivation {
-    name = "hax-docs";
-    unpackPhase = "true";
-    buildPhase = "true";
-    installPhase = ''
-      mkdir $out
-      cp -r ${frontend-docs}/share/doc $out/frontend
-      cp -r ${hax-engine.docs}         $out/engine
-      cd $out
-      INDEX=$(mktemp)
-      (
-        echo "<style>"
-        echo "body {font-family: Sans-Serif; margin: 0px; padding: 20px;}"
-        echo "h1 {font-size: 140%;  font-weight: inherit;}"
-        echo "</style>"
-        echo "<h1>Hax docs</h1>"
-        echo "<p>Hax is written both in Rust and OCaml. Documentation for each is available below:</p>"
-        echo "<ul>"
-        echo "<li><a href=\"frontend/hax_frontend_exporter/index.html\">Frontend documentation</a> (Rust)</li>"
-        echo "<li><a href=\"engine/hax-engine/index.html\">Engine documentation</a> (OCaml)</li>"
-        echo "</ul>"
-      ) > $INDEX
-      mv $INDEX index.html
-    '';
-  };
-  binaries = [hax hax-engine.bin rustc gcc];
-  tests = craneLib.buildPackage (commonArgs
-    // {
-      inherit cargoArtifacts;
-      pname = "hax-tests";
-      doCheck = true;
-      CI = "true";
-      cargoBuildCommand = "true";
-      checkPhaseCargoCommand = ''
-        SNAPS_DIR=test-harness/src/snapshots && rmdir "$SNAPS_DIR"
-        TESTS_DIR=tests                      && rmdir "$TESTS_DIR"
+  tests = craneLib.buildPackage (commonArgs // {
+    inherit cargoArtifacts;
+    pname = "hax-tests";
+    doCheck = true;
+    CI = "true";
+    cargoBuildCommand = "true";
+    checkPhaseCargoCommand = ''
+      SNAPS_DIR=test-harness/src/snapshots && rmdir "$SNAPS_DIR"
+      TESTS_DIR=tests                      && rmdir "$TESTS_DIR"
 
-        ln -s ${../test-harness/src/snapshots}        "$SNAPS_DIR"
-        cp -r --no-preserve=mode   ${../tests}        "$TESTS_DIR"
+      ln -s ${../test-harness/src/snapshots}        "$SNAPS_DIR"
+      cp -r --no-preserve=mode   ${../tests}        "$TESTS_DIR"
 
-        cargo test --test toolchain --profile release
+      cargo test --test toolchain --profile release
+    '';
+    buildInputs = binaries;
+    CARGO_TESTS_ASSUME_BUILT = "yes";
+  });
+in stdenv.mkDerivation {
+  name = hax.name;
+  buildInputs = [ makeWrapper ];
+  phases = [ "installPhase" ];
+  installPhase = ''
+    mkdir -p $out/bin
+    makeWrapper ${hax}/bin/cargo-hax $out/bin/cargo-hax \
+      --prefix PATH : ${lib.makeBinPath binaries}
+  '';
+  meta.mainProgram = "cargo-hax";
+  passthru = {
+    unwrapped = hax;
+    hax-engine-names-extract = craneLib.buildPackage (commonArgs // {
+      pname = "hax_engine_names_extract";
+      cargoLock = ../Cargo.lock;
+      cargoToml = ../engine/names/extract/Cargo.toml;
+      cargoArtifacts = hax_with_artifacts;
+      nativeBuildInputs = [ hax_with_artifacts ];
+      postUnpack = ''
+        cd $sourceRoot/engine/names/extract
+        sourceRoot="."
       '';
-      buildInputs = binaries;
-      CARGO_TESTS_ASSUME_BUILT = "yes";
     });
-in
-  stdenv.mkDerivation {
-    name = hax.name;
-    buildInputs = [makeWrapper];
-    phases = ["installPhase"];
-    installPhase = ''
-      mkdir -p $out/bin
-      makeWrapper ${hax}/bin/cargo-hax $out/bin/cargo-hax \
-        --prefix PATH : ${lib.makeBinPath binaries}
-    '';
-    meta.mainProgram = "cargo-hax";
-    passthru = {
-      unwrapped = hax;
-      hax-engine-names-extract = craneLib.buildPackage (
-        commonArgs
-        // {
-          pname = "hax_engine_names_extract";
-          cargoLock = ../Cargo.lock;
-          cargoToml = ../engine/names/extract/Cargo.toml;
-          cargoArtifacts = hax_with_artifacts;
-          nativeBuildInputs = [hax_with_artifacts];
-          postUnpack = ''
-            cd $sourceRoot/engine/names/extract
-            sourceRoot="."
-          '';
-        }
-      );
-      engine-docs = hax-engine.docs;
-      inherit tests docs frontend-docs;
-    };
-  }
+    inherit docs tests;
+  };
+}
diff --git a/docs/default.nix b/docs/default.nix
@@ -1,5 +1,6 @@
 { stdenv, buildPythonPackage, fetchPypi, setuptools, wheel, mkdocs
-, mkdocs-material }:
+, mkdocs-material, fetchFromGitHub, natsort, wcmatch, hax-frontend-docs
+, hax-engine-docs }:
 let
   mkdocs-glightbox = buildPythonPackage rec {
     pname = "mkdocs-glightbox";
@@ -32,7 +33,14 @@ let
 
 in stdenv.mkDerivation {
   name = "hax-docs";
+  src = ./..;
   buildInputs = [ mkdocs mkdocs-material mkdocs-glightbox mkdocs-nav-weight ];
-  buildPhase = "mkdocs build";
-  installPhase = "mv site $out";
+  buildPhase = ''
+    mkdocs build
+  '';
+  installPhase = ''
+    mv site $out
+    cp -rf ${hax-frontend-docs}/share/doc/ $out/frontend/docs
+    cp -rf ${hax-engine-docs} $out/engine/docs
+  '';
 }
diff --git a/docs/engine/arch.svg b/docs/engine/arch.svg
diff --git a/docs/engine/index.md b/docs/engine/index.md
@@ -1,6 +1,3 @@
 # Engine
 
-The hax engine.
-
-## Overview
-![Architecture diagram](arch.svg)
+The hax engine. Its [odoc](https://ocaml.github.io/odoc/) documentation can be found [here](./docs/hax-engine/index.html).