From acd0769a438b141bb1a955f7562cb6c7e3388771 Mon Sep 17 00:00:00 2001 From: Mathis Date: Wed, 29 May 2024 18:21:50 +0200 Subject: [PATCH] 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 --- .github/workflows/doc.yml | 49 +++++++++++++++++++++++++++++++++++++++ README.md | 10 ++++++++ cross-shell.nix | 7 +++--- flake.nix | 35 ++++++++++++++-------------- justfile | 3 +++ 5 files changed, 82 insertions(+), 22 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 0000000000..2f4449213e --- /dev/null +++ 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 '' > 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 15025ea3f8..7cafada546 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) @@ -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 index b9b3949d99..604dfd82c8 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 a01e9fe122..3eead31845 100644 --- 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,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 @@ -282,7 +282,7 @@ 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 index 2c49af7b3b..8a6596c8f7 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}}