From 64fc5663a0691fdffb44ff5e91d058a35bb5dd6d Mon Sep 17 00:00:00 2001 From: Kaur Kuut Date: Tue, 5 Nov 2024 14:51:39 +0200 Subject: [PATCH] Match CI doc testing with docs.rs. (#734) * Remove `-Zunstable-options -Zrustdoc-scrape-examples` from CI. It wasn't even enabled for docs.rs and we don't have any examples by Cargo's definition, 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. * Pass `--all-features` at docs.rs to match our CI and reduce the maintenance burden of manually syncing the features list. * Target only `x86_64-unknown-linux-gnu` on docs.rs as we don't have any platform specific docs. * 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. --- .github/workflows/ci.yml | 10 ++++++---- examples/scenes/src/test_scenes.rs | 2 +- vello/Cargo.toml | 6 ++++++ vello/src/lib.rs | 2 ++ vello/src/wgpu_engine.rs | 2 +- vello_encoding/Cargo.toml | 6 ++++++ vello_encoding/src/lib.rs | 2 ++ vello_shaders/Cargo.toml | 6 ++++++ vello_shaders/src/lib.rs | 2 ++ 9 files changed, 32 insertions(+), 6 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d7494239d..4498c399b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -366,15 +366,17 @@ 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 --all-features --no-deps --document-private-items -Zunstable-options -Zrustdoc-scrape-examples + run: cargo doc --workspace --locked --all-features --no-deps --document-private-items + env: + RUSTDOCFLAGS: '--cfg docsrs -D warnings' - # 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/examples/scenes/src/test_scenes.rs b/examples/scenes/src/test_scenes.rs index 233017d94..a2032676d 100644 --- a/examples/scenes/src/test_scenes.rs +++ b/examples/scenes/src/test_scenes.rs @@ -82,7 +82,7 @@ export_scenes!( ); /// Implementations for the test scenes. -/// In a module because the exported [`ExampleScene`](crate::ExampleScene) creation functions use the same names. +/// In a module because the exported [`ExampleScene`] creation functions use the same names. mod impls { use std::f64::consts::PI; diff --git a/vello/Cargo.toml b/vello/Cargo.toml index 46b2814c5..3bcba6b06 100644 --- a/vello/Cargo.toml +++ b/vello/Cargo.toml @@ -9,6 +9,12 @@ rust-version.workspace = true license.workspace = true repository.workspace = true +[package.metadata.docs.rs] +all-features = true +# There are no platform specific docs. +default-target = "x86_64-unknown-linux-gnu" +targets = [] + [features] default = ["wgpu"] # Enables GPU memory usage estimation. This performs additional computations diff --git a/vello/src/lib.rs b/vello/src/lib.rs index ea72f388a..923e24797 100644 --- a/vello/src/lib.rs +++ b/vello/src/lib.rs @@ -81,6 +81,8 @@ //! //! See the [`examples/`](https://github.com/linebender/vello/tree/main/examples) folder to see how that code integrates with frameworks like winit. +#![cfg_attr(docsrs, feature(doc_auto_cfg))] + mod debug; mod recording; mod render; diff --git a/vello/src/wgpu_engine.rs b/vello/src/wgpu_engine.rs index 549bfa586..0f80e5ddc 100644 --- a/vello/src/wgpu_engine.rs +++ b/vello/src/wgpu_engine.rs @@ -38,7 +38,7 @@ pub(crate) struct WgpuEngine { #[cfg(not(target_arch = "wasm32"))] shaders_to_initialise: Option>, pub(crate) use_cpu: bool, - /// Overrides from a specific `Image`'s [`id`](peniko::Image::id) to a wgpu `Texture`. + /// Overrides from a specific `Image::data`'s [`id`](peniko::Blob::id) to a wgpu `Texture`. /// /// The `Texture` should have the same size as the `Image`. pub(crate) image_overrides: HashMap>>, diff --git a/vello_encoding/Cargo.toml b/vello_encoding/Cargo.toml index 1a978acf9..5f3d66355 100644 --- a/vello_encoding/Cargo.toml +++ b/vello_encoding/Cargo.toml @@ -7,6 +7,12 @@ rust-version.workspace = true license.workspace = true repository.workspace = true +[package.metadata.docs.rs] +all-features = true +# There are no platform specific docs. +default-target = "x86_64-unknown-linux-gnu" +targets = [] + [features] default = ["full"] diff --git a/vello_encoding/src/lib.rs b/vello_encoding/src/lib.rs index 18f5bed40..45888de35 100644 --- a/vello_encoding/src/lib.rs +++ b/vello_encoding/src/lib.rs @@ -3,6 +3,8 @@ //! Raw scene encoding. +#![cfg_attr(docsrs, feature(doc_auto_cfg))] + mod binning; mod clip; mod config; diff --git a/vello_shaders/Cargo.toml b/vello_shaders/Cargo.toml index 9cbafe0b1..01ff141ca 100644 --- a/vello_shaders/Cargo.toml +++ b/vello_shaders/Cargo.toml @@ -7,6 +7,12 @@ rust-version.workspace = true license.workspace = true repository.workspace = true +[package.metadata.docs.rs] +all-features = true +# There are no platform specific docs. +default-target = "x86_64-unknown-linux-gnu" +targets = [] + [features] default = ["wgsl", "full", "cpu"] compile = ["dep:naga", "dep:thiserror"] diff --git a/vello_shaders/src/lib.rs b/vello_shaders/src/lib.rs index 6fab45b31..217d61c1e 100644 --- a/vello_shaders/src/lib.rs +++ b/vello_shaders/src/lib.rs @@ -17,6 +17,8 @@ //! //! [Vello]: https://github.com/linebender/vello +#![cfg_attr(docsrs, feature(doc_auto_cfg))] + mod types; #[cfg(feature = "compile")]