feat(docs): Add Rust dependency graph generation, enable workspace in…

…dexing for Rust docs (#120)

* add dependency graph generation, enable workspace indexing for Rust docs

* fix spelling

* add cargo modules docs generation

* fix BUILD udc args

* add more than one crate

* fix earthly

* fix

* fix RUSTDOCFLAGS assigning

* update docs

* fix spelling

* revert RUSTDOCFLAGS update

* fix

* update

---------

Co-authored-by: Steven Johnson <stevenj@users.noreply.github.com>

docs/src/guides/languages/rust.md

@@ -9,7 +9,7 @@ tags:
 # :simple-rust: Rust
 <!-- markdownlint-enable single-h1 -->
 
-<!-- cspell: words USERARCH TARGETARCH toolsets fmtchk stdcfgs rustfmt nextest testci testdocs -->
+<!-- cspell: words USERARCH TARGETARCH toolsets fmtchk stdcfgs rustfmt nextest testci testdocs depgraph -->
 
 ## Introduction
 
@@ -55,7 +55,7 @@ VERSION 0.7
 builder:
     FROM ./../../earthly/rust+rust-base
 
-    COPY --dir .cargo .config benches src tests .
+    COPY --dir .cargo .config crates .
     COPY Cargo.lock Cargo.toml .
     COPY clippy.toml deny.toml rustfmt.toml .
 
@@ -145,12 +145,12 @@ The same approach we will see for the another targets of this guide.
 build-hosted:
     FROM +builder
  
-    DO ./../../earthly/rust+BUILD
+    DO ./../../earthly/rust+BUILD --libs="bar" --bins="foo/foo"
 
-    DO ./../../earthly/rust+SMOKE_TEST --bin=hello_world
+    DO ./../../earthly/rust+SMOKE_TEST --bin="foo"
 
     SAVE ARTIFACT target/$TARGETARCH/doc doc
-    SAVE ARTIFACT target/$TARGETARCH/release/hello_world hello_world
+    SAVE ARTIFACT target/$TARGETARCH/release/foo foo
 
 # Test which runs check with all supported host tooling.  Needs qemu or rosetta to run.
 # Only used to validate tooling is working across host toolsets.
@@ -182,6 +182,13 @@ Important to note that in this particular example we are dealing with the execut
 so it produces binary as a final artifact.
 Another case of the building Rust library we will consider later.
 Actual build process is done with `+BUILD` UDC target.
+The `+BUILD` UDC have few arguments `libs` and `bins`,
+they should be specified to properly generate `cargo-modules` docs (see description below).
+The `libs` argument takes a list of library crate's names in your Rust project, e.g.
+`--libs="crate1 crate2"`.
+The `bins` argument takes a list of binary crate's names and binary names in your Rust project, e.g.
+`--bins="crate1/bin1 crate1/bin2 crate2/bin1"`, note that each binary name correspond to each crate
+and separated in this list with `/` symbol.
 Under this build process we perform different steps of compiling and validating of our Rust project,
 here is the list of steps (look at `./earthly/rust/scripts/std_build.sh`):
 
@@ -196,6 +203,13 @@ look at `./earthly/rust/stdcfgs/config.toml`)Checking Self contained Unit tests
 5. `cargo testdocs` ([cargo alias](https://doc.rust-lang.org/cargo/reference/config.html#alias),
 look at `./earthly/rust/stdcfgs/config.toml`)Checking Documentation tests all pass.
 6. `cargo bench` - Checking Benchmarks all run to completion.
+7. `cargo depgraph` - Generating dependency graph based on the Rust code.
+Generated artifacts are `doc/workspace.dot`, `doc/full.dot`, `doc/all.dot` files.
+8. `cargo modules` - Generating modules trees and graphs based on the Rust code.
+Generated artifacts are `doc/$crate.$bin.bin.modules.tree`, `doc/$crate.$bin.bin.modules.dot`
+for the specified `--bins="crate1/bin1"` argument
+and `target/doc/$crate.lib.modules.tree`, `target/doc/$crate.lib.modules.dot`
+for the specified `--libs="crate1"` argument of the `+BUILD` UDC.
 
 Next steps is mandatory if you are going to produce a binary as an artifact,
 for Rust libraries the are not mandatory and could be omitted.

earthly/rust/Earthfile

@@ -1,7 +1,7 @@
 # Common Rust UDCs and Builders.
 VERSION 0.7
 
-# cspell: words rustup miri nextest ripgrep colordiff rustfmt stdcfgs toolset readelf
+# cspell: words rustup miri nextest ripgrep colordiff rustfmt stdcfgs toolset readelf depgraph
 # cspell: words TARGETPLATFORM TARGETOS TARGETARCH TARGETVARIANT USERPLATFORM USEROS USERARCH USERVARIANT
 
 # Base Rustup build container.
@@ -60,7 +60,8 @@ rust-base:
         cargo install cargo-machete --version=0.6.0  && \
         cargo install refinery_cli  --version=0.8.11 && \
         cargo install cargo-deny    --version=0.14.3 && \
-        cargo install cargo-modules --version=0.10.2
+        cargo install cargo-modules --version=0.10.2 && \
+        cargo install cargo-depgraph --version=1.5.0
 
     SAVE ARTIFACT $CARGO_HOME/bin/refinery refinery
 
@@ -112,10 +113,15 @@ CHECK:
     RUN /scripts/std_checks.sh
 
 # Step we do during the `build` CI phase for all Rust programs
+# Parameters:
+#  * libs : The list of lib crates `cargo-modules` docs to build.
+#  * bins : The list of binaries `cargo-modules` docs to build.
 BUILD:
     COMMAND
+    ARG libs=""
+    ARG bins=""
 
-    RUN /scripts/std_build.sh
+    RUN /scripts/std_build.sh "$libs" "$bins"
 
 # Check if the build executable, isn't a busted mess.
 SMOKE_TEST:

earthly/rust/scripts/std_build.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 
-# cspell: words testci testdocs
+# cspell: words testci testdocs RUSTDOCFLAGS Zunstable depgraph
 
 # This script is run inside the `check` stage for rust projects to perform all 
 # high level non-compilation checks.
@@ -42,14 +42,30 @@ status $rc "Checking Documentation tests all pass" \
 status $rc "Checking Benchmarks all run to completion" \
     cargo bench --all-targets; rc=$?
 
-## Generate Module Trees for documentation purposes.
-# cargo modules generate tree --orphans --types --traits --fns --tests --all-features --lib
-# cargo modules generate tree --orphans --types --traits --fns --tests --all-features --bin <name>
-
-## Generate Module Graphs for documentation purposes.
-#  cargo modules generate graph --all-features --types --traits --fns --modules --uses --externs --acyclic --lib
-#  cargo modules generate graph --all-features --types --traits --fns --modules --uses --externs --acyclic --bin <name>
+## Generate dependency graphs
+cargo depgraph --workspace-only --dedup-transitive-deps > target/doc/workspace.dot
+cargo depgraph --dedup-transitive-deps > target/doc/full.dot
+cargo depgraph --all-deps --dedup-transitive-deps > target/doc/all.dot
 
+export NO_COLOR=1
+## Generate Module Trees for documentation purposes.
+for lib in $1;
+do
+    cargo modules generate tree --orphans --types --traits --tests --all-features \
+        --package $lib --lib > target/doc/$lib.lib.modules.tree; rc=$?
+
+    cargo modules generate graph --all-features --modules \
+        --package $lib --lib > target/doc/$lib.lib.modules.dot; rc=$?
+done
+for bin in $2;
+do
+    IFS="/" read -r package bin <<< "$bin"
+    cargo modules generate tree --orphans --types --traits --tests --all-features \
+        --package $package --bin $bin > target/doc/$package.$bin.bin.modules.tree; rc=$?
+
+    cargo modules generate graph --all-features --modules \
+        --package $package --bin $bin > target/doc/$package.$bin.bin.modules.dot; rc=$?
+done
 
 # Return an error if any of this fails.
 exit $rc

earthly/rust/stdcfgs/cargo_config.toml

@@ -49,6 +49,9 @@ rustflags = [
 ]
 
 rustdocflags = [
+    "--enable-index-page",
+    "-Z",
+    "unstable-options",
     "-D",
     "warnings",
     "-D",
@@ -104,7 +107,6 @@ lto = "thin"
 incremental = false
 codegen-units = 16
 
-
 [alias]
 lint = "clippy -- -D warnings -D clippy::pedantic -D clippy::unwrap_used -D clippy::expect_used -D clippy::exit -D clippy::get_unwrap -D clippy::index_refutable_slice -D clippy::indexing_slicing -D clippy::match_on_vec_items -D clippy::match_wild_err_arm -D clippy::missing_panics_doc -D clippy::panic -D clippy::string_slice -D clippy::unchecked_duration_subtraction -D clippy::unreachable -D clippy::missing_docs_in_private_items"
 lintfix = "clippy -- -D warnings -D clippy::pedantic -D clippy::unwrap_used -D clippy::expect_used -D clippy::exit -D clippy::get_unwrap -D clippy::index_refutable_slice -D clippy::indexing_slicing -D clippy::match_on_vec_items -D clippy::match_wild_err_arm -D clippy::missing_panics_doc -D clippy::panic -D clippy::string_slice -D clippy::unchecked_duration_subtraction -D clippy::unreachable"

examples/rust/.cargo/config.toml

@@ -49,6 +49,9 @@ rustflags = [
 ]
 
 rustdocflags = [
+    "--enable-index-page",
+    "-Z",
+    "unstable-options",
     "-D",
     "warnings",
     "-D",
@@ -104,7 +107,6 @@ lto = "thin"
 incremental = false
 codegen-units = 16
 
-
 [alias]
 lint = "clippy -- -D warnings -D clippy::pedantic -D clippy::unwrap_used -D clippy::expect_used -D clippy::exit -D clippy::get_unwrap -D clippy::index_refutable_slice -D clippy::indexing_slicing -D clippy::match_on_vec_items -D clippy::match_wild_err_arm -D clippy::missing_panics_doc -D clippy::panic -D clippy::string_slice -D clippy::unchecked_duration_subtraction -D clippy::unreachable -D clippy::missing_docs_in_private_items"
 lintfix = "clippy -- -D warnings -D clippy::pedantic -D clippy::unwrap_used -D clippy::expect_used -D clippy::exit -D clippy::get_unwrap -D clippy::index_refutable_slice -D clippy::indexing_slicing -D clippy::match_on_vec_items -D clippy::match_wild_err_arm -D clippy::missing_panics_doc -D clippy::panic -D clippy::string_slice -D clippy::unchecked_duration_subtraction -D clippy::unreachable"

examples/rust/Cargo.toml

@@ -1,27 +1,14 @@
-[package]
-name = "hello_world"
-version = "0.1.0"
+[workspace]
+resolver = "2"
+members = [
+    "crates/foo",
+    "crates/bar",
+]
+
+[workspace.package]
 edition = "2021"
+version = "0.0.1"
 license = "MIT OR Apache-2.0"
 
-[dependencies]
-clap = {version= "4.4.7", features = ["derive" ] }
 
-[dev-dependencies]
-criterion = { version = "0.5.1", features = ["html_reports"] }
 
-[lib]
-name = "hello_world_lib"
-path = "src/lib.rs"
-
-[[bin]]
-name = "hello_world"
-path = "src/main.rs"
-
-[[test]]
-name = "integration_test"
-harness = false
-
-[[bench]]
-name = "benchmark"
-harness = false

examples/rust/Earthfile

@@ -6,7 +6,7 @@ VERSION 0.7
 builder:
     FROM ./../../earthly/rust+rust-base
 
-    COPY --dir .cargo .config benches src tests .
+    COPY --dir .cargo .config crates .
     COPY Cargo.lock Cargo.toml .
     COPY clippy.toml deny.toml rustfmt.toml .
 
@@ -28,12 +28,12 @@ check-all-hosts:
 build-hosted:
     FROM +builder
 
-    DO ./../../earthly/rust+BUILD
+    DO ./../../earthly/rust+BUILD --libs="bar" --bins="foo/foo"
 
-    DO ./../../earthly/rust+SMOKE_TEST --bin=hello_world
+    DO ./../../earthly/rust+SMOKE_TEST --bin="foo"
 
     SAVE ARTIFACT target/$TARGETARCH/doc doc
-    SAVE ARTIFACT target/$TARGETARCH/release/hello_world hello_world
+    SAVE ARTIFACT target/$TARGETARCH/release/foo foo
 
 # Test which runs check with all supported host tooling.  Needs qemu or rosetta to run.
 # Only used to validate tooling is working across host toolsets.

examples/rust/crates/bar/Cargo.toml

@@ -0,0 +1,9 @@
+[package]
+name = "bar"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]

examples/rust/crates/bar/src/lib.rs

@@ -0,0 +1,17 @@
+//! This is the bar crate
+
+/// Adds two numbers
+pub fn add(left: usize, right: usize) -> usize {
+    left + right
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn it_works() {
+        let result = add(2, 2);
+        assert_eq!(result, 4);
+    }
+}

examples/rust/crates/foo/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "foo"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+clap = {version= "4.4.7", features = ["derive" ] }
+
+[dev-dependencies]
+criterion = { version = "0.5.1", features = ["html_reports"] }
+
+[[test]]
+name = "integration_test"
+harness = false
+
+[[bench]]
+name = "benchmark"
+harness = false

examples/rust/src/main.rs → examples/rust/crates/foo/src/main.rs

@@ -2,7 +2,7 @@
 //! Used as a test of the Rust CI/CD pipeline.
 
 use clap::Parser;
-use hello_world_lib::fmt_hello;
+use foo::fmt_hello;
 
 /// Simple program to greet a person
 #[derive(Parser, Debug)]