From 691ed10d4b4d381b0f5b3e7796479ea96f970e73 Mon Sep 17 00:00:00 2001 From: sveitser Date: Wed, 29 May 2024 14:23:52 +0200 Subject: [PATCH] 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}}