From 4dc11b7449cd942787b4df4f507b3ad5b204587b Mon Sep 17 00:00:00 2001 From: Fredi Raspall Date: Thu, 20 Nov 2025 20:27:06 +0100 Subject: [PATCH 1/6] chore: add just recipe to test docs Signed-off-by: Fredi Raspall --- justfile | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/justfile b/justfile index d59b5425d..02ba63905 100644 --- a/justfile +++ b/justfile @@ -171,9 +171,25 @@ cargo *args: declare -rx RUSTFLAGS="${RUSTFLAGS_DEBUG}" fi - export RUSTDOCFLAGS="${RUSTDOCFLAGS:-} ${RUSTFLAGS} --html-in-header $(pwd)/scripts/doc/custom-header.html" + export RUSTDOCFLAGS="${RUSTDOCFLAGS:-} ${RUSTFLAGS} --html-in-header $(pwd)/scripts/doc/custom-header.html --document-private-items" ./compile-env/bin/cargo "${extra_args[@]}" + +# Here we may list external crates for which we want docs because +# the workspace crates' documentations refer to them. +external := "left-right etherparse dataplane-dpdk-sys" + +# Generate docs for the crates in this project +[script] +docs: + export RUSTDOCFLAGS="--html-in-header $(pwd)/scripts/doc/custom-header.html --document-private-items --allow rustdoc::all" + for crate in {{ external }}; do + echo "Documenting $crate..." + ./compile-env/bin/cargo doc -p $crate --no-deps + done + ./compile-env/bin/cargo doc --workspace --no-deps + + # Run the (very minimal) compile environment [script] compile-env *args: From c565c8b666492d4db0c96d100925f5dd51697b55 Mon Sep 17 00:00:00 2001 From: Fredi Raspall Date: Thu, 20 Nov 2025 20:27:51 +0100 Subject: [PATCH 2/6] chore: misc lint changes to silence broken links Signed-off-by: Fredi Raspall --- dpdk/src/lib.rs | 1 + nat/src/lib.rs | 1 + tracectl/src/control.rs | 2 +- 3 files changed, 3 insertions(+), 1 deletion(-) diff --git a/dpdk/src/lib.rs b/dpdk/src/lib.rs index 4b06491c0..f01bdce13 100644 --- a/dpdk/src/lib.rs +++ b/dpdk/src/lib.rs @@ -29,6 +29,7 @@ #![warn(clippy::all)] #![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic)] #![deny(rustdoc::all)] +#![allow(rustdoc::broken_intra_doc_links)] #![allow(private_bounds)] extern crate alloc; extern crate core; diff --git a/nat/src/lib.rs b/nat/src/lib.rs index b28d4b0d6..846ed54ad 100644 --- a/nat/src/lib.rs +++ b/nat/src/lib.rs @@ -3,6 +3,7 @@ #![deny(clippy::all, clippy::pedantic)] #![deny(rustdoc::all)] +#![allow(rustdoc::broken_intra_doc_links)] #![allow(clippy::missing_errors_doc)] //! Network Address Translation (NAT) for the dataplane diff --git a/tracectl/src/control.rs b/tracectl/src/control.rs index 9c8485419..941b5817c 100644 --- a/tracectl/src/control.rs +++ b/tracectl/src/control.rs @@ -372,7 +372,7 @@ impl TracingControl { Ok(db.default) } - /// Parse a string made of comma-separated tag=level; level = [off,error,warn,info,debug,trace] + /// Parse a string made of comma-separated tag=level; level = \[`off,error,warn,info,debug,trace`\] fn parse_tracing_config(input: &str) -> Result, TraceCtlError> { let mut result = OrderMap::new(); From 6b591abe9896a15ff2adb431196aaf2034e87de0 Mon Sep 17 00:00:00 2001 From: Fredi Raspall Date: Thu, 20 Nov 2025 20:28:35 +0100 Subject: [PATCH 3/6] chore: temporary experiment for ci Signed-off-by: Fredi Raspall --- .github/workflows/dev.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/dev.yml b/.github/workflows/dev.yml index 039926da8..2aa0a056b 100644 --- a/.github/workflows/dev.yml +++ b/.github/workflows/dev.yml @@ -310,11 +310,11 @@ jobs: - id: "docs" name: "run rustdoc" run: | - RUSTDOCFLAGS="-D warnings" just \ + RUSTDOCFLAGS="-D warnings --document-private-items --allow rustdoc::all" just \ debug_justfile="${{matrix.debug_justfile}}" \ profile=${{matrix.profile.name}} \ target=x86_64-unknown-linux-gnu \ - ${{matrix.profile.sterile}} cargo doc + ${{matrix.profile.sterile}} cargo doc --workspace --no-deps - name: "Setup tmate session for debug" if: ${{ failure() && github.event_name == 'workflow_dispatch' && inputs.debug_enabled }} From 6a6800a8a0a6a76750010ae46ac4ce1ff1e66701 Mon Sep 17 00:00:00 2001 From: Fredi Raspall Date: Thu, 20 Nov 2025 22:10:07 +0100 Subject: [PATCH 4/6] chore: don't run clippy for dependencies Signed-off-by: Fredi Raspall --- .github/workflows/dev.yml | 2 +- justfile | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/dev.yml b/.github/workflows/dev.yml index 2aa0a056b..c171f73d9 100644 --- a/.github/workflows/dev.yml +++ b/.github/workflows/dev.yml @@ -305,7 +305,7 @@ jobs: name: "run clippy" run: | just debug_justfile="${{matrix.debug_justfile}}" profile=${{matrix.profile.name}} \ - ${{matrix.profile.sterile}} cargo clippy --all-targets --all-features -- -D warnings + ${{matrix.profile.sterile}} cargo clippy --workspace --no-deps --all-targets --all-features -- -D warnings - id: "docs" name: "run rustdoc" diff --git a/justfile b/justfile index 02ba63905..019917230 100644 --- a/justfile +++ b/justfile @@ -530,7 +530,7 @@ print-container-tags: # Run Clippy like you're in CI [script] -clippy *args: (cargo "clippy" "--all-targets" "--all-features" args "--" "-D" "warnings") +clippy *args: (cargo "clippy" "--workspace" "--no-deps" "--all-targets" "--all-features" args "--" "-D" "warnings") # Serve rustdoc output locally (using port 8000) [script] From eed1bbf6c2d0926da77276ba9555d3bc8a0aa6c2 Mon Sep 17 00:00:00 2001 From: Fredi Raspall Date: Thu, 20 Nov 2025 22:58:46 +0100 Subject: [PATCH 5/6] chore: disable docs except release Signed-off-by: Fredi Raspall --- .github/workflows/dev.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/dev.yml b/.github/workflows/dev.yml index c171f73d9..7155e4e7f 100644 --- a/.github/workflows/dev.yml +++ b/.github/workflows/dev.yml @@ -309,6 +309,7 @@ jobs: - id: "docs" name: "run rustdoc" + if: ${{matrix.profile.name == 'release'}} run: | RUSTDOCFLAGS="-D warnings --document-private-items --allow rustdoc::all" just \ debug_justfile="${{matrix.debug_justfile}}" \ From 308ec7632dbfc42c9807398ca026cce8971d8845 Mon Sep 17 00:00:00 2001 From: Fredi Raspall Date: Fri, 21 Nov 2025 19:56:55 +0100 Subject: [PATCH 6/6] chore: still playing Allow skipping docs based on label Signed-off-by: Fredi Raspall --- .github/workflows/dev.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/dev.yml b/.github/workflows/dev.yml index 7155e4e7f..291257477 100644 --- a/.github/workflows/dev.yml +++ b/.github/workflows/dev.yml @@ -309,7 +309,7 @@ jobs: - id: "docs" name: "run rustdoc" - if: ${{matrix.profile.name == 'release'}} + if: ${{ matrix.profile.name == 'release' && !contains(github.event.pull_request.labels.*.name, 'disable-docs') }} run: | RUSTDOCFLAGS="-D warnings --document-private-items --allow rustdoc::all" just \ debug_justfile="${{matrix.debug_justfile}}" \