From 81c86ff3fc3405b23e9743b478131e0c0d14ad1f Mon Sep 17 00:00:00 2001 From: Kaur Kuut Date: Tue, 5 Nov 2024 16:04:14 +0200 Subject: [PATCH] Match CI doc testing with docs.rs. (#19) * Remove `-Zunstable-options -Zrustdoc-scrape-examples` from CI. It wasn't even enabled for docs.rs and we don't have any examples, so not worth enabling scraping at this point. * Treat doc warnings as errors. Historically we've not done so due to various `rustdoc` bugs giving false positives but I got it to pass without failure right now, so perhaps better times have arrived. * Enable the `doc_auto_cfg` feature for docs.rs which will show a little tip next to feature gated functionality informing of the crate feature flag. * Pass `--all-features` at docs.rs to match our CI and reduce the maintenance burden of manually syncing the features list. --- .github/workflows/ci.yml | 10 ++++++---- android_trace/Cargo.toml | 14 ++++++++------ android_trace/src/lib.rs | 1 + tracing_android_trace/Cargo.toml | 14 ++++++++------ tracing_android_trace/src/lib.rs | 1 + 5 files changed, 24 insertions(+), 16 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 55487be..bf26873 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -184,9 +184,11 @@ jobs: with: save-if: ${{ github.event_name != 'merge_group' }} - # We test documentation using nightly to match docs.rs. This prevents potential breakages + # We test documentation using nightly to match docs.rs. - name: cargo doc - run: cargo doc --workspace --locked --target aarch64-linux-android --all-features --no-deps --document-private-items -Zunstable-options -Zrustdoc-scrape-examples + run: cargo doc --workspace --locked --target aarch64-linux-android --all-features --no-deps --document-private-items + env: + RUSTDOCFLAGS: '--cfg docsrs -D warnings' docs-compile: name: cargo test --doc @@ -214,11 +216,11 @@ jobs: - name: cargo test --doc run: cargo test --doc --workspace --locked --target aarch64-linux-android --all-features -Zdoctest-xcompile - # If this fails, consider changing your text or adding something to .typos.toml + # If this fails, consider changing your text or adding something to .typos.toml. typos: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: check typos - uses: crate-ci/typos@v1.26.0 + uses: crate-ci/typos@v1.27.0 diff --git a/android_trace/Cargo.toml b/android_trace/Cargo.toml index 88ea2dc..a1fc081 100644 --- a/android_trace/Cargo.toml +++ b/android_trace/Cargo.toml @@ -11,6 +11,14 @@ rust-version.workspace = true repository.workspace = true edition.workspace = true +[package.metadata.docs.rs] +all-features = true +# There are no platform specific docs. +# In theory, we could add the other Android targets here. +# However, the API is identical across all of them, so there's no advantage. +default-target = "aarch64-linux-android" +targets = [] + [lints] workspace = true @@ -26,9 +34,3 @@ api_level_29 = ["api_level_23"] [dev-dependencies] static_assertions = "1.1.0" - -[package.metadata.docs.rs] -default-target = "aarch64-linux-android" -# In theory, we could add the other Android targets here. -# However, the API is identical across any of them, so there's no advantage -targets = [] diff --git a/android_trace/src/lib.rs b/android_trace/src/lib.rs index 983864d..d4772ab 100644 --- a/android_trace/src/lib.rs +++ b/android_trace/src/lib.rs @@ -12,6 +12,7 @@ //! .rustdoc-hidden { display: none; } //! #![doc = include_str!("../README.md")] +#![cfg_attr(docsrs, feature(doc_auto_cfg))] #[cfg(not(feature = "api_level_23"))] use ffi::ATraceAPILevel23Methods; diff --git a/tracing_android_trace/Cargo.toml b/tracing_android_trace/Cargo.toml index 257ed08..1c12da2 100644 --- a/tracing_android_trace/Cargo.toml +++ b/tracing_android_trace/Cargo.toml @@ -15,6 +15,14 @@ rust-version.workspace = true repository.workspace = true edition.workspace = true +[package.metadata.docs.rs] +all-features = true +# There are no platform specific docs. +# In theory, we could add the other Android targets here. +# However, the API is identical across all of them, so there's no advantage. +default-target = "aarch64-linux-android" +targets = [] + [lints] workspace = true @@ -44,9 +52,3 @@ static_assertions = "1.1.0" # We only depend on android_trace on Android so that we can customise the # `compile_error` message android_trace = { workspace = true, default-features = false } - -[package.metadata.docs.rs] -default-target = "aarch64-linux-android" -# In theory, we could add the other Android targets here. -# However, the API is identical across any of them, so there's no advantage -targets = [] diff --git a/tracing_android_trace/src/lib.rs b/tracing_android_trace/src/lib.rs index 5b8b280..caea526 100644 --- a/tracing_android_trace/src/lib.rs +++ b/tracing_android_trace/src/lib.rs @@ -17,6 +17,7 @@ //! .rustdoc-hidden { display: none; } //! #![doc = include_str!("../README.md")] +#![cfg_attr(docsrs, feature(doc_auto_cfg))] #![forbid(unsafe_code)] #[cfg(not(target_os = "android"))]