Merge pull request #677 from antiguru/test_mdbook

Test mdbook using regular doc tests

Author: frankmcsherry

.github/workflows/test.yml

@@ -26,6 +26,8 @@ jobs:
           components: clippy
       - name: Cargo test
         run: cargo test --workspace --all-targets
+      - name: Cargo doc test
+        run: cargo test --doc
 
   # Check for clippy warnings
   clippy:
@@ -40,19 +42,3 @@ jobs:
         run: cargo clippy --workspace --all-targets
         env:
           RUSTFLAGS: "" # Don't make test fail on clippy
-
-  # Check mdbook files for errors
-  mdbook:
-    name: test mdBook
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions-rust-lang/setup-rust-toolchain@v1
-        # rustdoc doesn't build dependencies, so it needs to run after `cargo build`,
-        # but its dependency search gets confused if there are multiple copies of any
-        # dependency in target/debug/deps, so it needs to run before `cargo test` et al.
-        # clutter target/debug/deps with multiple copies of things.
-      - run: cargo clean
-      - run: cargo build
-      - name: test mdBook
-        run: for file in $(find mdbook -name '*.md' | sort); do rustdoc --test $file  -L ./target/debug/deps; done

Cargo.toml

@@ -4,6 +4,7 @@ members = [
     "communication",
     "container",
     "logging",
+    "mdbook",
     "timely",
 ]
 

mdbook/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "mdbook"
+version = "0.0.0"
+edition.workspace = true
+publish = false
+
+[lints]
+workspace = true
+
+[dependencies]
+timely = { path = "../timely" }
+timely_bytes = { path = "../bytes" }
+timely_communication = { path = "../communication" }
+serde = "1.0"

mdbook/build.rs

@@ -0,0 +1,46 @@
+//! Infrastructure to test the mdbook documentation.
+//!
+//! Generates a module for each Markdown file in the `src/` directory, and includes
+//! the contents of each file as a doc comment for that module.
+
+use std::env;
+use std::fs;
+use std::io;
+use std::path::{Path, PathBuf};
+
+/// Recursively finds all Markdown files in the given path and collects their paths into `mds`.
+fn find_mds(dir: impl AsRef<Path>, mds: &mut Vec<PathBuf>) -> io::Result<()> {
+    for entry in fs::read_dir(dir)? {
+        let path = entry?.path();
+        if path.is_dir() {
+            find_mds(path, mds)?;
+        } else if path.extension().and_then(|s| s.to_str()) == Some("md") {
+            mds.push(path);
+        }
+    }
+    Ok(())
+}
+
+fn main() -> io::Result<()> {
+    let mut mds = Vec::new();
+    find_mds("src", &mut mds)?;
+
+    let mut lib = String::new();
+
+    for md in mds {
+        let md_path = md.to_str().unwrap();
+        println!("cargo::rerun-if-changed={md_path}");
+        let mod_name = md_path.replace(['/', '\\', '-', '.'], "_");
+        use std::fmt::Write;
+        writeln!(
+            &mut lib,
+            "#[allow(non_snake_case)] #[doc = include_str!(concat!(env!(\"CARGO_MANIFEST_DIR\"), r\"{}{md_path}\"))] mod {mod_name} {{}}",
+            std::path::MAIN_SEPARATOR,
+        ).unwrap();
+    }
+
+    let dest_path = Path::new(&env::var("OUT_DIR").unwrap()).join("mdbook.rs");
+    fs::write(&dest_path, lib)?;
+    println!("cargo::rerun-if-changed=build.rs");
+    Ok(())
+}

mdbook/src/lib.rs

@@ -0,0 +1,2 @@
+//! Dummy library file to allow testing the mdbook documentation.
+include!(concat!(env!("OUT_DIR"), "/mdbook.rs"));