Generate rust docs and publish (#1518)

* Generate rust docs and publish - Fix compilation by adding RUSTDOCFLAGS - Add CI job to publish docs (modified from hotshot) - Add a just recipe - Update README Close #1517 * Change doc CI job name * Fix cross compilation dev shell Put rust env vars into a nix attrset to avoid repeating them many times * Set RUSTFLAGS in doc CI job
EspressoSystems · Jun 3, 2024 · acd0769 · acd0769
1 parent ea43e38
commit acd0769
Show file tree

Hide file tree

Showing 5 changed files with 82 additions and 22 deletions.
diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
@@ -0,0 +1,49 @@
+name: Documentation
+on:
+  push:
+    branches:
+      - "main"
+      - "release-*"
+  pull_request:
+  schedule:
+    - cron: "0 0 * * 1"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ (github.ref == 'refs/heads/main' && github.run_number) || github.ref }}
+  cancel-in-progress: true
+
+env:
+  RUSTFLAGS: --cfg async_executor_impl="async-std" --cfg async_channel_impl="async-std"
+  RUSTDOCFLAGS: --cfg async_executor_impl="async-std" --cfg async_channel_impl="async-std"
+
+jobs:
+  doc:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Install Just
+        run: sudo apt-get install -y just
+
+      - uses: Swatinem/rust-cache@v2
+        name: Enable Rust Caching
+
+      - name: Build Docs
+        run: |
+          just doc
+
+      - name: Create documentation
+        if: ${{ github.ref == 'refs/heads/main' }}
+        run: |
+          cp -R target/doc public
+          echo '<meta http-equiv="refresh" content="0; url=sequencer">' > public/index.html
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v4
+        if: ${{ github.ref == 'refs/heads/main' }}
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./public
+          cname: sequencer.docs.espressosys.com
diff --git a/README.md b/README.md
@@ -1,6 +1,7 @@
 # Espresso Sequencer
 
 [![Build](https://github.com/EspressoSystems/espresso-sequencer/actions/workflows/build.yml/badge.svg)](https://github.com/EspressoSystems/espresso-sequencer/actions/workflows/build.yml)
+[![Docs](https://github.com/EspressoSystems/espresso-sequencer/actions/workflows/doc.yml/badge.svg)](https://github.com/EspressoSystems/espresso-sequencer/actions/workflows/doc.yml)
 [![Contracts](https://github.com/EspressoSystems/espresso-sequencer/actions/workflows/contracts.yml/badge.svg)](https://github.com/EspressoSystems/espresso-sequencer/actions/workflows/contracts.yml)
 [![Lint](https://github.com/EspressoSystems/espresso-sequencer/actions/workflows/lint.yml/badge.svg)](https://github.com/EspressoSystems/espresso-sequencer/actions/workflows/lint.yml)
 [![Audit](https://github.com/EspressoSystems/espresso-sequencer/actions/workflows/audit.yml/badge.svg)](https://github.com/EspressoSystems/espresso-sequencer/actions/workflows/audit.yml)
@@ -56,6 +57,15 @@ a dockerized Espresso Sequencer network with an example Layer 2 rollup applicati
 - Activate the environment with `nix-shell`, or `nix develop`, or `direnv allow` if using [direnv](https://direnv.net/).
 - For installation without nix please see [ubuntu.md](./doc/ubuntu.md).
 
+## Documentation
+The rust code documentation can be found at
+[http://sequencer.docs.espressosys.com](http://sequencer.docs.espressosys.com).
+Please note the disclaimer about API stability at the end of the readme.
+
+To generate the documentation locally and view it in the browser, run
+
+    just doc --open
+
 ## Run the tests
 
     just pull # to pull docker images

diff --git a/cross-shell.nix b/cross-shell.nix
@@ -1,7 +1,7 @@
 # A simplest nix shell file with the project dependencies and
 # a cross-compilation support.
-{ pkgs, RUSTFLAGS, RUST_LOG, RUST_BACKTRACE, CARGO_TARGET_DIR }:
-pkgs.mkShell {
+{ pkgs, envVars }:
+pkgs.mkShell (envVars // {
   # Native project dependencies like build utilities and additional routines
   # like container building, linters, etc.
   nativeBuildInputs = with pkgs.pkgsBuildHost; [
@@ -25,5 +25,4 @@ pkgs.mkShell {
     rustCrossHook
   ];
 
-  inherit RUSTFLAGS RUST_LOG RUST_BACKTRACE CARGO_TARGET_DIR;
-}
+})
diff --git a/flake.nix b/flake.nix
@@ -49,10 +49,12 @@
       # node=error: disable noisy anvil output
       RUST_LOG = "info,libp2p=off,isahc=error,surf=error,node=error";
       RUST_BACKTRACE = 1;
-      RUSTFLAGS =
-        " --cfg async_executor_impl=\"async-std\" --cfg async_channel_impl=\"async-std\" --cfg hotshot_example";
+      ASYNC_FLAGS = " --cfg async_executor_impl=\"async-std\" --cfg async_channel_impl=\"async-std\" ";
+      RUSTFLAGS = "${ASYNC_FLAGS} --cfg hotshot_example";
+      RUSTDOCFLAGS = ASYNC_FLAGS;
       # Use a distinct target dir for builds from within nix shells.
       CARGO_TARGET_DIR = "target/nix";
+      rustEnvVars = { inherit RUST_LOG RUST_BACKTRACE RUSTFLAGS RUSTDOCFLAGS CARGO_TARGET_DIR; };
 
       solhintPkg = { buildNpmPackage, fetchFromGitHub }:
         buildNpmPackage rec {
@@ -90,10 +92,11 @@
             inherit overlays localSystem crossSystem;
           };
         in
-        import ./cross-shell.nix {
-          inherit pkgs;
-          inherit RUST_LOG RUST_BACKTRACE RUSTFLAGS CARGO_TARGET_DIR;
-        };
+        import ./cross-shell.nix
+          {
+            inherit pkgs;
+            envVars = rustEnvVars;
+          };
     in
     with pkgs; {
       checks = {
@@ -180,7 +183,7 @@
           '';
           solc = pkgs.solc-bin.latest;
         in
-        mkShell {
+        mkShell (rustEnvVars // {
           buildInputs = [
             # Rust dependencies
             pkg-config
@@ -231,8 +234,7 @@
           '' + self.checks.${system}.pre-commit-check.shellHook;
           RUST_SRC_PATH = "${stableToolchain}/lib/rustlib/src/rust/library";
           FOUNDRY_SOLC = "${solc}/bin/solc";
-          inherit RUST_LOG RUST_BACKTRACE RUSTFLAGS CARGO_TARGET_DIR;
-        };
+        });
       devShells.crossShell =
         crossShell { config = "x86_64-unknown-linux-musl"; };
       devShells.armCrossShell =
@@ -243,7 +245,7 @@
             extensions = [ "rustfmt" "clippy" "llvm-tools-preview" "rust-src" ];
           };
         in
-        mkShell {
+        mkShell (rustEnvVars // {
           buildInputs = [
             # Rust dependencies
             pkg-config
@@ -252,13 +254,12 @@
             protobuf # to compile libp2p-autonat
             toolchain
           ];
-          inherit RUST_LOG RUST_BACKTRACE RUSTFLAGS CARGO_TARGET_DIR;
-        };
+        });
       devShells.coverage =
         let
           toolchain = pkgs.rust-bin.nightly.latest.minimal;
         in
-        mkShell {
+        mkShell (rustEnvVars // {
           buildInputs = [
             # Rust dependencies
             pkg-config
@@ -268,21 +269,20 @@
             toolchain
             grcov
           ];
-          inherit RUST_LOG RUST_BACKTRACE RUSTFLAGS CARGO_TARGET_DIR;
           CARGO_INCREMENTAL = "0";
           shellHook = ''
             RUSTFLAGS="$RUSTFLAGS -Zprofile -Ccodegen-units=1 -Cinline-threshold=0 -Clink-dead-code -Coverflow-checks=off -Cpanic=abort -Zpanic_abort_tests -Cdebuginfo=2"
           '';
           RUSTDOCFLAGS = "-Zprofile -Ccodegen-units=1 -Cinline-threshold=0 -Clink-dead-code -Coverflow-checks=off -Cpanic=abort -Zpanic_abort_tests";
-        };
+        });
 
       devShells.rustShell =
         let
           stableToolchain = pkgs.rust-bin.stable.latest.minimal.override {
             extensions = [ "rustfmt" "clippy" "llvm-tools-preview" "rust-src" ];
           };
         in
-        mkShell {
+        mkShell (rustEnvVars // {
           buildInputs = [
             # Rust dependencies
             pkg-config
@@ -291,7 +291,6 @@
             protobuf # to compile libp2p-autonat
             stableToolchain
           ];
-          inherit RUST_LOG RUST_BACKTRACE RUSTFLAGS CARGO_TARGET_DIR;
-        };
+        });
     });
 }
diff --git a/justfile b/justfile
@@ -1,6 +1,9 @@
 default:
     just --list
 
+doc *args:
+    cargo doc --no-deps --document-private-items {{args}}
+
 demo *args:
     docker compose up {{args}}