From d81cb46be02e883ecf3d7b1f2b06523f8df5f480 Mon Sep 17 00:00:00 2001 From: i509VCB Date: Wed, 26 Oct 2022 16:07:25 -0500 Subject: [PATCH] enable doc_auto_cfg for docs.rs (#3113) * enable doc_auto_cfg for docs.rs This should expose more feature labels in the generated documentation and removes the needs for the manually labeling the features for a type, function or enum variants. * enable docsrs cfg when building docs for master --- .github/workflows/docs.yml | 1 + wgpu-core/Cargo.toml | 4 ++++ wgpu-core/src/lib.rs | 1 + wgpu-hal/Cargo.toml | 9 +++++++++ wgpu-hal/src/lib.rs | 1 + wgpu-types/Cargo.toml | 4 ++++ wgpu-types/src/lib.rs | 1 + wgpu/src/lib.rs | 6 +----- 8 files changed, 22 insertions(+), 5 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index df6278700..fa0c49e7e 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -30,6 +30,7 @@ jobs: - name: Build the docs (nightly) run: | cargo +nightly doc --no-deps --lib + env: RUSTDOCFLAGS="--cfg docsrs" - name: Build the docs (stable) run: cargo +stable doc --no-deps --lib diff --git a/wgpu-core/Cargo.toml b/wgpu-core/Cargo.toml index 4f5000da1..c92865b73 100644 --- a/wgpu-core/Cargo.toml +++ b/wgpu-core/Cargo.toml @@ -9,6 +9,10 @@ repository.workspace = true keywords.workspace = true license.workspace = true +[package.metadata.docs.rs] +all-features = true +rustdoc-args = ["--cfg", "docsrs"] + [lib] [features] diff --git a/wgpu-core/src/lib.rs b/wgpu-core/src/lib.rs index b3ed54204..c13fff083 100644 --- a/wgpu-core/src/lib.rs +++ b/wgpu-core/src/lib.rs @@ -3,6 +3,7 @@ * into other language-specific user-friendly libraries. */ +#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))] #![allow( // It is much clearer to assert negative conditions with eq! false clippy::bool_assert_comparison, diff --git a/wgpu-hal/Cargo.toml b/wgpu-hal/Cargo.toml index eb5f539e3..5a0ce3afb 100644 --- a/wgpu-hal/Cargo.toml +++ b/wgpu-hal/Cargo.toml @@ -10,6 +10,15 @@ keywords.workspace = true license.workspace = true rust-version.workspace = true +[package.metadata.docs.rs] +# Ideally we would enable all the features. +# +# However the metal features fails to be documented because the docs.rs runner cross compiling under +# x86_64-unknown-linux-gnu and metal-rs cannot compile in that environment at the moment. The same applies +# with the dx11 and dx12 features. +features = ["vulkan", "gles", "renderdoc"] +rustdoc-args = ["--cfg", "docsrs"] + [lib] [features] diff --git a/wgpu-hal/src/lib.rs b/wgpu-hal/src/lib.rs index 02fa24643..b32f372de 100644 --- a/wgpu-hal/src/lib.rs +++ b/wgpu-hal/src/lib.rs @@ -14,6 +14,7 @@ * - secondary backends (DX11/GLES): 0.5 each */ +#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))] #![allow( // for `if_then_panic` until it reaches stable unknown_lints, diff --git a/wgpu-types/Cargo.toml b/wgpu-types/Cargo.toml index 56d8d99d9..44b046e37 100644 --- a/wgpu-types/Cargo.toml +++ b/wgpu-types/Cargo.toml @@ -9,6 +9,10 @@ repository.workspace = true keywords.workspace = true license.workspace = true +[package.metadata.docs.rs] +all-features = true +rustdoc-args = ["--cfg", "docsrs"] + [lib] [features] diff --git a/wgpu-types/src/lib.rs b/wgpu-types/src/lib.rs index 3e91ae034..ec5b0dd8a 100644 --- a/wgpu-types/src/lib.rs +++ b/wgpu-types/src/lib.rs @@ -2,6 +2,7 @@ * This API is used for targeting both Web and Native. */ +#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))] #![allow( // We don't use syntax sugar where it's not necessary. clippy::match_like_matches_macro, diff --git a/wgpu/src/lib.rs b/wgpu/src/lib.rs index d5b6a16ac..7338e7df4 100644 --- a/wgpu/src/lib.rs +++ b/wgpu/src/lib.rs @@ -2,7 +2,7 @@ //! //! To start using the API, create an [`Instance`]. -#![cfg_attr(docsrs, feature(doc_cfg))] // Allow doc(cfg(feature = "")) for showing in docs that something is feature gated. +#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))] #![doc(html_logo_url = "https://raw.githubusercontent.com/gfx-rs/wgpu/master/logo.png")] #![warn(missing_docs)] @@ -843,13 +843,11 @@ pub enum ShaderSource<'a> { /// /// See also: [`util::make_spirv`], [`include_spirv`] #[cfg(feature = "spirv")] - #[cfg_attr(docsrs, doc(cfg(feature = "spirv")))] SpirV(Cow<'a, [u32]>), /// GLSL module as a string slice. /// /// Note: GLSL is not yet fully supported and must be a specific ShaderStage. #[cfg(feature = "glsl")] - #[cfg_attr(docsrs, doc(cfg(feature = "glsl")))] Glsl { /// The source code of the shader. shader: Cow<'a, str>, @@ -860,11 +858,9 @@ pub enum ShaderSource<'a> { }, /// WGSL module as a string slice. #[cfg(feature = "wgsl")] - #[cfg_attr(docsrs, doc(cfg(feature = "wgsl")))] Wgsl(Cow<'a, str>), /// Naga module. #[cfg(feature = "naga")] - #[cfg_attr(docsrs, doc(cfg(feature = "naga")))] Naga(Cow<'static, naga::Module>), /// Dummy variant because `Naga` doesn't have a lifetime and without enough active features it /// could be the last one active.