Add docs.rs build check script and CI job (#188)

rcoh · web-flow · commit e135d1ee5c71 · 2026-01-16T11:32:55.000-05:00
✍️ *Description of changes:* The [docs.rs build](https://docs.rs/crate/metrique-aggregation/latest/builds/2825680) failed for metrique aggregation because of a bug (? I am investigating) where even though the dev-dependency included the `emf` feature, it wans't available when scraping the example. This PR: 1. Fixes the issue by adding a `__build_examples` feature 2. Adds a new script and CI target that faithfully simulate docs.rs build by actually packaging each crate first 3. Adds this script to GitHub actions I verified that the github action failed before I added the fix: https://github.com/awslabs/metrique/actions/runs/21071514566/job/60602148756 🔏 *By submitting this pull request* - [x] I confirm that I've made a best effort attempt to update all relevant documentation. - [x] I confirm that my contribution is made under the terms of the Apache 2.0 license.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -1,5 +1,7 @@
 name: Build
 on: [pull_request]
+permissions:
+  contents: read
 
 jobs:
   build:
@@ -28,3 +30,13 @@ jobs:
         with:
           toolchain: ${{ matrix.toolchain }}
           flags: ${{ matrix.flags }}
+
+  docs-rs:
+    name: Docs.rs Build Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@nightly
+      - uses: dtolnay/install@cargo-docs-rs
+      - name: Check docs.rs build
+        run: ./scripts/check-docsrs.sh
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/metrique-aggregation/Cargo.toml b/metrique-aggregation/Cargo.toml
@@ -5,9 +5,11 @@ edition = "2024"
 rust-version = "1.89" # build.yml
 license = "Apache-2.0"
 description = "Library for working with unit of work metrics - aggregation"
+repository = "https://github.com/awslabs/metrique"
+readme = "README.md"
 
 [dependencies]
-metrique = { path = "../metrique", version = "0.1"}
+metrique = { path = "../metrique", version = "0.1" }
 metrique-writer = { path = "../metrique-writer", version = "0.1.14" }
 metrique-core = { path = "../metrique-core", version = "0.1.12" }
 metrique-macro = { path = "../metrique-macro", version = "0.1.11" }
@@ -33,10 +35,21 @@ uuid = { version = "1", features = ["v4"] }
 tracing.workspace = true
 tracing-subscriber = { workspace = true, features = ["env-filter"] }
 
+[features]
+# There seems to be a rustdoc bug where when a dev dependency enables a new feature, its not picked up properly
+__build_examples_for_rustdoc = ["metrique/emf", "metrique/test-util"]
+
 # We need to name one example so that our examples that use dev-dependencies get scraped
 [[example]]
 name = "embedded"
 doc-scrape-examples = true
+requires_features = ["__build_examples_for_rustdoc"]
+
+[package.metadata.docs.rs]
+all-features = true
+targets = ["x86_64-unknown-linux-gnu"]
+rustdoc-args = ["--cfg", "docsrs"]
+cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
 
 [[bench]]
 name = "aggregation"
diff --git a/metrique-core/Cargo.toml b/metrique-core/Cargo.toml
@@ -20,3 +20,4 @@ metrique-writer = { path = "../metrique-writer" }
 all-features = true
 targets = ["x86_64-unknown-linux-gnu"]
 rustdoc-args = ["--cfg", "docsrs"]
+cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
diff --git a/metrique-macro/Cargo.toml b/metrique-macro/Cargo.toml
@@ -29,3 +29,4 @@ assert2 = { workspace = true }
 all-features = true
 targets = ["x86_64-unknown-linux-gnu"]
 rustdoc-args = ["--cfg", "docsrs"]
+cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
diff --git a/metrique-metricsrs/Cargo.toml b/metrique-metricsrs/Cargo.toml
@@ -48,3 +48,9 @@ metrique-metricsrs = { path = ".", features = ["metrics-rs-024", "test-util"] }
 tokio = { workspace = true, features = ["macros", "test-util"] }
 rand = { workspace = true }
 rstest = { workspace = true }
+
+[package.metadata.docs.rs]
+all-features = true
+targets = ["x86_64-unknown-linux-gnu"]
+rustdoc-args = ["--cfg", "docsrs"]
+cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
diff --git a/metrique-service-metrics/Cargo.toml b/metrique-service-metrics/Cargo.toml
@@ -22,3 +22,4 @@ tracing-appender = { workspace = true }
 all-features = true
 targets = ["x86_64-unknown-linux-gnu"]
 rustdoc-args = ["--cfg", "docsrs"]
+cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
diff --git a/metrique-timesource/Cargo.toml b/metrique-timesource/Cargo.toml
@@ -25,3 +25,4 @@ tokio = { workspace = true, features = ["test-util", "full"] }
 all-features = true
 targets = ["x86_64-unknown-linux-gnu"]
 rustdoc-args = ["--cfg", "docsrs"]
+cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
diff --git a/metrique-writer-core/Cargo.toml b/metrique-writer-core/Cargo.toml
@@ -38,3 +38,4 @@ private-test-util = ["dep:tracing"]
 all-features = true
 targets = ["x86_64-unknown-linux-gnu"]
 rustdoc-args = ["--cfg", "docsrs"]
+cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
diff --git a/metrique-writer-format-emf/Cargo.toml b/metrique-writer-format-emf/Cargo.toml
@@ -42,3 +42,4 @@ metrics_024 = { workspace = true }
 all-features = true
 targets = ["x86_64-unknown-linux-gnu"]
 rustdoc-args = ["--cfg", "docsrs"]
+cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
diff --git a/metrique-writer-macro/Cargo.toml b/metrique-writer-macro/Cargo.toml
@@ -23,3 +23,4 @@ syn = { workspace = true }
 all-features = true
 targets = ["x86_64-unknown-linux-gnu"]
 rustdoc-args = ["--cfg", "docsrs"]
+cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
diff --git a/metrique-writer/Cargo.toml b/metrique-writer/Cargo.toml
@@ -82,3 +82,4 @@ ordered-float = ["dep:ordered-float"]
 all-features = true
 targets = ["x86_64-unknown-linux-gnu"]
 rustdoc-args = ["--cfg", "docsrs"]
+cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
diff --git a/metrique/tests/cargo-toml-format.rs b/metrique/tests/cargo-toml-format.rs
@@ -101,6 +101,57 @@ fn test_cargo_toml_format(
             msrv_major_minor()
         );
     }
+
+    // Check that each package has docs.rs metadata
+    if let Some(package) = package {
+        let metadata = toml
+            .get("package")
+            .and_then(|p| p.get("metadata"))
+            .and_then(|m| m.get("docs"))
+            .and_then(|d| d.get("rs"))
+            .and_then(|r| r.as_table())
+            .unwrap_or_else(|| {
+                panic!(
+                    "Missing [package.metadata.docs.rs] section in {}",
+                    toml_path.display()
+                )
+            });
+
+        assert!(
+            metadata.contains_key("all-features"),
+            "[package.metadata.docs.rs] in {} must have 'all-features' key",
+            toml_path.display()
+        );
+
+        assert!(
+            metadata.contains_key("rustdoc-args"),
+            "[package.metadata.docs.rs] in {} must have 'rustdoc-args' key",
+            toml_path.display()
+        );
+
+        // Check for -Zrustdoc-scrape-examples in cargo-args
+        let cargo_args = metadata
+            .get("cargo-args")
+            .and_then(|a| a.as_array())
+            .unwrap_or_else(|| {
+                panic!(
+                    "[package.metadata.docs.rs] in {} must have 'cargo-args' array with '-Zrustdoc-scrape-examples'",
+                    toml_path.display()
+                )
+            });
+
+        let has_scrape_examples = cargo_args.iter().any(|arg| {
+            arg.as_str()
+                .map(|s| s == "-Zrustdoc-scrape-examples")
+                .unwrap_or(false)
+        });
+
+        assert!(
+            has_scrape_examples,
+            "[package.metadata.docs.rs] cargo-args in {} must include '-Zrustdoc-scrape-examples'",
+            toml_path.display()
+        );
+    }
 }
 
 #[rstest]
diff --git a/scripts/check-docsrs.sh b/scripts/check-docsrs.sh
@@ -0,0 +1,51 @@
+#!/bin/bash
+set -e
+
+# Simulate docs.rs build for metrique packages
+# Usage:
+#   ./scripts/check-docsrs.sh           # Run on all workspace packages
+#   ./scripts/check-docsrs.sh <package> # Run on specific package
+
+# Determine the target to use based on installed nightly targets
+TARGET=$(rustup target list --installed --toolchain nightly | head -1)
+
+check_package() {
+    local pkg_name=$1
+    local pkg_version=$2
+
+    echo "→ Checking docs.rs build for $pkg_name..."
+
+    # Because of workspace unification, we need to actually package the individual packages,
+    # then attempt to document the package itself to detect failure in the presence of
+    # of some bugs.
+    cargo package -p "$pkg_name" --allow-dirty
+
+    (cd "target/package/$pkg_name-$pkg_version" && \
+        cargo +nightly docs-rs --target "$TARGET")
+}
+
+if [ $# -eq 0 ]; then
+    # Run on all workspace packages
+    packages=$(cargo metadata --no-deps --format-version 1 | \
+        jq -r '.packages[] | "\(.name) \(.version)"')
+
+    while IFS= read -r line; do
+        pkg_name=$(echo "$line" | cut -d' ' -f1)
+        pkg_version=$(echo "$line" | cut -d' ' -f2)
+        check_package "$pkg_name" "$pkg_version"
+    done <<< "$packages"
+else
+    # Run on specific package
+    pkg_name=$1
+    pkg_version=$(cargo metadata --no-deps --format-version 1 | \
+        jq -r ".packages[] | select(.name == \"$pkg_name\") | .version")
+
+    if [ -z "$pkg_version" ]; then
+        echo "Error: Package $pkg_name not found in workspace"
+        exit 1
+    fi
+
+    check_package "$pkg_name" "$pkg_version"
+fi
+
+echo "✓ All docs.rs checks passed!"
