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

.github/workflows/doc.yml

@@ -0,0 +1,48 @@
+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:
+  RUSTDOCFLAGS: --cfg async_executor_impl="async-std" --cfg async_channel_impl="async-std"
+
+jobs:
+  build:
+    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

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)
@@ -28,6 +29,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

flake.nix

@@ -49,8 +49,9 @@
       # 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";
 
@@ -92,7 +93,7 @@
         in
         import ./cross-shell.nix {
           inherit pkgs;
-          inherit RUST_LOG RUST_BACKTRACE RUSTFLAGS CARGO_TARGET_DIR;
+          inherit RUST_LOG RUST_BACKTRACE RUSTFLAGS RUSTDOCFLAGS CARGO_TARGET_DIR;
         };
     in
     with pkgs; {
@@ -231,7 +232,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;
+          inherit RUST_LOG RUST_BACKTRACE RUSTFLAGS RUSTDOCFLAGS CARGO_TARGET_DIR;
         };
       devShells.crossShell =
         crossShell { config = "x86_64-unknown-linux-musl"; };
@@ -252,7 +253,7 @@
             protobuf # to compile libp2p-autonat
             toolchain
           ];
-          inherit RUST_LOG RUST_BACKTRACE RUSTFLAGS CARGO_TARGET_DIR;
+          inherit RUST_LOG RUST_BACKTRACE RUSTFLAGS RUSTDOCFLAGS CARGO_TARGET_DIR;
         };
       devShells.coverage =
         let
@@ -291,7 +292,7 @@
             protobuf # to compile libp2p-autonat
             stableToolchain
           ];
-          inherit RUST_LOG RUST_BACKTRACE RUSTFLAGS CARGO_TARGET_DIR;
+          inherit RUST_LOG RUST_BACKTRACE RUSTFLAGS RUSTDOCFLAGS CARGO_TARGET_DIR;
         };
     });
 }

justfile

@@ -1,6 +1,9 @@
 default:
     just --list
 
+doc *args:
+    cargo doc --no-deps --document-private-items {{args}}
+
 demo *args:
     docker compose up {{args}}