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

@@ -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

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]

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,

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]

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,

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]

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,

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.