From 691ed10d4b4d381b0f5b3e7796479ea96f970e73 Mon Sep 17 00:00:00 2001 From: sveitser Date: Wed, 29 May 2024 14:23:52 +0200 Subject: [PATCH 1/4] 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 | 48 +++++++++++++++++++++++++++++++++++++++ README.md | 10 ++++++++ flake.nix | 13 ++++++----- justfile | 3 +++ 4 files changed, 68 insertions(+), 6 deletions(-) create mode 100644 .github/workflows/doc.yml diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml new file mode 100644 index 000000000..cf7601134 --- /dev/null +++ b/.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 '' > 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 index 2e83826a5..8b92a2e80 100644 --- 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) @@ -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 diff --git a/flake.nix b/flake.nix index a01e9fe12..134792eda 100644 --- a/flake.nix +++ b/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; }; }); } diff --git a/justfile b/justfile index 2c49af7b3..8a6596c8f 100644 --- 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}} From 89c5ed7fd37ceb9461b73a9aac02061d6ee92671 Mon Sep 17 00:00:00 2001 From: sveitser Date: Wed, 29 May 2024 14:29:54 +0200 Subject: [PATCH 2/4] Change doc CI job name --- .github/workflows/doc.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml index cf7601134..c32cc4098 100644 --- a/.github/workflows/doc.yml +++ b/.github/workflows/doc.yml @@ -17,7 +17,7 @@ env: RUSTDOCFLAGS: --cfg async_executor_impl="async-std" --cfg async_channel_impl="async-std" jobs: - build: + doc: runs-on: ubuntu-24.04 steps: - name: Checkout Repository From 85a26f5c9c957d1c1a6bbcc0e851587046ed9511 Mon Sep 17 00:00:00 2001 From: sveitser Date: Wed, 29 May 2024 18:05:02 +0200 Subject: [PATCH 3/4] Fix cross compilation dev shell Put rust env vars into a nix attrset to avoid repeating them many times --- cross-shell.nix | 7 +++---- flake.nix | 30 ++++++++++++++---------------- 2 files changed, 17 insertions(+), 20 deletions(-) diff --git a/cross-shell.nix b/cross-shell.nix index b9b3949d9..604dfd82c 100644 --- 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 index 134792eda..3eead3184 100644 --- a/flake.nix +++ b/flake.nix @@ -54,6 +54,7 @@ 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 { @@ -91,10 +92,11 @@ inherit overlays localSystem crossSystem; }; in - import ./cross-shell.nix { - inherit pkgs; - inherit RUST_LOG RUST_BACKTRACE RUSTFLAGS RUSTDOCFLAGS CARGO_TARGET_DIR; - }; + import ./cross-shell.nix + { + inherit pkgs; + envVars = rustEnvVars; + }; in with pkgs; { checks = { @@ -181,7 +183,7 @@ ''; solc = pkgs.solc-bin.latest; in - mkShell { + mkShell (rustEnvVars // { buildInputs = [ # Rust dependencies pkg-config @@ -232,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 RUSTDOCFLAGS CARGO_TARGET_DIR; - }; + }); devShells.crossShell = crossShell { config = "x86_64-unknown-linux-musl"; }; devShells.armCrossShell = @@ -244,7 +245,7 @@ extensions = [ "rustfmt" "clippy" "llvm-tools-preview" "rust-src" ]; }; in - mkShell { + mkShell (rustEnvVars // { buildInputs = [ # Rust dependencies pkg-config @@ -253,13 +254,12 @@ protobuf # to compile libp2p-autonat toolchain ]; - inherit RUST_LOG RUST_BACKTRACE RUSTFLAGS RUSTDOCFLAGS CARGO_TARGET_DIR; - }; + }); devShells.coverage = let toolchain = pkgs.rust-bin.nightly.latest.minimal; in - mkShell { + mkShell (rustEnvVars // { buildInputs = [ # Rust dependencies pkg-config @@ -269,13 +269,12 @@ 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 @@ -283,7 +282,7 @@ extensions = [ "rustfmt" "clippy" "llvm-tools-preview" "rust-src" ]; }; in - mkShell { + mkShell (rustEnvVars // { buildInputs = [ # Rust dependencies pkg-config @@ -292,7 +291,6 @@ protobuf # to compile libp2p-autonat stableToolchain ]; - inherit RUST_LOG RUST_BACKTRACE RUSTFLAGS RUSTDOCFLAGS CARGO_TARGET_DIR; - }; + }); }); } From 9e5f709ebed06a86a1ee2e1556ea6c08c7998801 Mon Sep 17 00:00:00 2001 From: sveitser Date: Wed, 29 May 2024 18:06:16 +0200 Subject: [PATCH 4/4] Set RUSTFLAGS in doc CI job --- .github/workflows/doc.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml index c32cc4098..2f4449213 100644 --- a/.github/workflows/doc.yml +++ b/.github/workflows/doc.yml @@ -14,6 +14,7 @@ concurrency: 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: