Make feature(doc_auto_cfg) work (#12642)

# Objective

- In #12366 `![cfg_attr(docsrs, feature(doc_auto_cfg))] `was added. But
to apply it it needs `--cfg=docsrs` in rustdoc-args.


## Solution

- Apply `--cfg=docsrs` to all crates and CI.

I also added `[package.metadata.docs.rs]` to all crates to avoid adding
code behind a feature and forget adding the metadata.

Before:

![Screenshot 2024-03-22 at 00 51
57](https://github.com/bevyengine/bevy/assets/104745335/6a9dfdaa-8710-4784-852b-5f9b74e3522c)

After:
![Screenshot 2024-03-22 at 00 51
32](https://github.com/bevyengine/bevy/assets/104745335/c5bd6d8e-8ddb-45b3-b844-5ecf9f88961c)

Author: ameknite

.github/workflows/docs.yml

@@ -49,6 +49,9 @@ jobs:
           echo "<meta name=\"robots\" content=\"noindex\">" > header.html
 
       - name: Build docs
+        env:
+          # needs to be in sync with [package.metadata.docs.rs]
+          RUSTDOCFLAGS:  -Zunstable-options --cfg=docsrs
         run: cargo doc --all-features --no-deps -p bevy -Zunstable-options -Zrustdoc-scrape-examples
 
       #  This adds the following:

Cargo.toml

@@ -2821,5 +2821,6 @@ lto = "fat"
 panic = "abort"
 
 [package.metadata.docs.rs]
-cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
+rustdoc-args = ["-Zunstable-options", "--cfg", "docsrs"]
 all-features = true
+cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]

crates/bevy_a11y/Cargo.toml

@@ -18,3 +18,7 @@ accesskit = "0.12"
 
 [lints]
 workspace = true
+
+[package.metadata.docs.rs]
+rustdoc-args = ["-Zunstable-options", "--cfg", "docsrs"]
+all-features = true

crates/bevy_a11y/src/lib.rs

@@ -1,6 +1,7 @@
-//! Accessibility for Bevy
-
 #![forbid(unsafe_code)]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+
+//! Accessibility for Bevy
 
 use std::sync::{
     atomic::{AtomicBool, Ordering},

crates/bevy_animation/Cargo.toml

@@ -40,3 +40,7 @@ uuid = { version = "1.7", features = ["v4"] }
 
 [lints]
 workspace = true
+
+[package.metadata.docs.rs]
+rustdoc-args = ["-Zunstable-options", "--cfg", "docsrs"]
+all-features = true

crates/bevy_animation/src/lib.rs

@@ -1,3 +1,5 @@
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+
 //! Animation for the game engine Bevy
 
 mod animatable;

crates/bevy_app/Cargo.toml

@@ -36,4 +36,5 @@ web-sys = { version = "0.3", features = ["Window"] }
 workspace = true
 
 [package.metadata.docs.rs]
+rustdoc-args = ["-Zunstable-options", "--cfg", "docsrs"]
 all-features = true

crates/bevy_app/src/lib.rs

@@ -1,6 +1,7 @@
-//! This crate is about everything concerning the highest-level, application layer of a Bevy app.
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
 
+//! This crate is about everything concerning the highest-level, application layer of a Bevy app.
+
 mod app;
 mod main_schedule;
 mod plugin;

crates/bevy_asset/Cargo.toml

@@ -61,4 +61,5 @@ bevy_log = { path = "../bevy_log", version = "0.14.0-dev" }
 workspace = true
 
 [package.metadata.docs.rs]
+rustdoc-args = ["-Zunstable-options", "--cfg", "docsrs"]
 all-features = true

crates/bevy_asset/macros/Cargo.toml

@@ -20,3 +20,7 @@ quote = "1.0"
 
 [lints]
 workspace = true
+
+[package.metadata.docs.rs]
+rustdoc-args = ["-Zunstable-options", "--cfg", "docsrs"]
+all-features = true

crates/bevy_asset/macros/src/lib.rs

@@ -1,5 +1,6 @@
 // FIXME(3492): remove once docs are ready
 #![allow(missing_docs)]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 
 use bevy_macro_utils::BevyManifest;
 use proc_macro::{Span, TokenStream};

crates/bevy_audio/Cargo.toml

@@ -52,4 +52,5 @@ android_shared_stdcxx = ["cpal/oboe-shared-stdcxx"]
 workspace = true
 
 [package.metadata.docs.rs]
+rustdoc-args = ["-Zunstable-options", "--cfg", "docsrs"]
 all-features = true

crates/bevy_audio/src/lib.rs

@@ -1,3 +1,6 @@
+#![forbid(unsafe_code)]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+
 //! Audio support for the game engine Bevy
 //!
 //! ```no_run
@@ -19,8 +22,6 @@
 //!     });
 //! }
 //! ```
-#![forbid(unsafe_code)]
-#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 
 mod audio;
 mod audio_output;

crates/bevy_color/Cargo.toml

@@ -21,3 +21,7 @@ encase = { version = "0.7", default-features = false }
 
 [lints]
 workspace = true
+
+[package.metadata.docs.rs]
+rustdoc-args = ["-Zunstable-options", "--cfg", "docsrs"]
+all-features = true

crates/bevy_color/src/lib.rs

@@ -1,3 +1,5 @@
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+
 //! Representations of colors in various color spaces.
 //!
 //! This crate provides a number of color representations, including:

crates/bevy_core/Cargo.toml

@@ -37,4 +37,5 @@ crossbeam-channel = "0.5.0"
 workspace = true
 
 [package.metadata.docs.rs]
+rustdoc-args = ["-Zunstable-options", "--cfg", "docsrs"]
 all-features = true

crates/bevy_core/src/lib.rs

@@ -1,6 +1,7 @@
-//! This crate provides core functionality for Bevy Engine.
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
 
+//! This crate provides core functionality for Bevy Engine.
+
 mod name;
 #[cfg(feature = "serialize")]
 mod serde;

crates/bevy_core_pipeline/Cargo.toml

@@ -42,4 +42,5 @@ nonmax = "0.5"
 workspace = true
 
 [package.metadata.docs.rs]
+rustdoc-args = ["-Zunstable-options", "--cfg", "docsrs"]
 all-features = true

crates/bevy_derive/Cargo.toml

@@ -19,3 +19,7 @@ syn = { version = "2.0", features = ["full"] }
 
 [lints]
 workspace = true
+
+[package.metadata.docs.rs]
+rustdoc-args = ["-Zunstable-options", "--cfg", "docsrs"]
+all-features = true

crates/bevy_derive/src/lib.rs

@@ -1,5 +1,6 @@
 // FIXME(3492): remove once docs are ready
 #![allow(missing_docs)]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 
 extern crate proc_macro;
 

crates/bevy_dev_tools/Cargo.toml

@@ -43,4 +43,5 @@ ron = { version = "0.8.0", optional = true }
 workspace = true
 
 [package.metadata.docs.rs]
+rustdoc-args = ["-Zunstable-options", "--cfg", "docsrs"]
 all-features = true

crates/bevy_dev_tools/src/lib.rs

@@ -1,6 +1,7 @@
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+
 //! This crate provides additional utilities for the [Bevy game engine](https://bevyengine.org),
 //! focused on improving developer experience.
-#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 
 use bevy_app::prelude::*;
 

crates/bevy_diagnostic/Cargo.toml

@@ -38,4 +38,5 @@ sysinfo = { version = "0.30.0", optional = true, default-features = false }
 workspace = true
 
 [package.metadata.docs.rs]
+rustdoc-args = ["-Zunstable-options", "--cfg", "docsrs"]
 all-features = true

crates/bevy_dylib/Cargo.toml

@@ -16,3 +16,7 @@ bevy_internal = { path = "../bevy_internal", version = "0.14.0-dev", default-fea
 
 [lints]
 workspace = true
+
+[package.metadata.docs.rs]
+rustdoc-args = ["-Zunstable-options", "--cfg", "docsrs"]
+all-features = true

crates/bevy_dylib/src/lib.rs

@@ -1,4 +1,4 @@
-#![allow(clippy::single_component_path_imports)]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 
 //! Forces dynamic linking of Bevy.
 //!
@@ -51,4 +51,5 @@
 
 // Force linking of the main bevy crate
 #[allow(unused_imports)]
+#[allow(clippy::single_component_path_imports)]
 use bevy_internal;

crates/bevy_dynamic_plugin/Cargo.toml

@@ -18,3 +18,7 @@ thiserror = "1.0"
 
 [lints]
 workspace = true
+
+[package.metadata.docs.rs]
+rustdoc-args = ["-Zunstable-options", "--cfg", "docsrs"]
+all-features = true

crates/bevy_dynamic_plugin/src/lib.rs

@@ -1,3 +1,5 @@
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+
 //! Bevy's dynamic plugin loading functionality.
 //!
 //! This crate allows loading dynamic libraries (`.dylib`, `.so`) that export a single

crates/bevy_ecs/Cargo.toml

@@ -51,4 +51,5 @@ path = "examples/change_detection.rs"
 workspace = true
 
 [package.metadata.docs.rs]
+rustdoc-args = ["-Zunstable-options", "--cfg", "docsrs"]
 all-features = true

crates/bevy_ecs/macros/Cargo.toml

@@ -17,3 +17,7 @@ proc-macro2 = "1.0"
 
 [lints]
 workspace = true
+
+[package.metadata.docs.rs]
+rustdoc-args = ["-Zunstable-options", "--cfg", "docsrs"]
+all-features = true

crates/bevy_ecs/macros/src/lib.rs

@@ -1,5 +1,6 @@
 // FIXME(3492): remove once docs are ready
 #![allow(missing_docs)]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 
 extern crate proc_macro;
 

crates/bevy_encase_derive/Cargo.toml

@@ -17,3 +17,7 @@ encase_derive_impl = "0.7"
 
 [lints]
 workspace = true
+
+[package.metadata.docs.rs]
+rustdoc-args = ["-Zunstable-options", "--cfg", "docsrs"]
+all-features = true

crates/bevy_encase_derive/src/lib.rs

@@ -1,5 +1,6 @@
 // FIXME(3492): remove once docs are ready
 #![allow(missing_docs)]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 
 use bevy_macro_utils::BevyManifest;
 use encase_derive_impl::{implement, syn};

crates/bevy_gilrs/Cargo.toml

@@ -22,3 +22,7 @@ thiserror = "1.0"
 
 [lints]
 workspace = true
+
+[package.metadata.docs.rs]
+rustdoc-args = ["-Zunstable-options", "--cfg", "docsrs"]
+all-features = true

crates/bevy_gilrs/src/lib.rs

@@ -1,3 +1,5 @@
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+
 //! Systems and type definitions for gamepad handling in Bevy.
 //!
 //! This crate is built on top of [GilRs](gilrs), a library

crates/bevy_gizmos/Cargo.toml

@@ -34,4 +34,5 @@ bytemuck = "1.0"
 workspace = true
 
 [package.metadata.docs.rs]
+rustdoc-args = ["-Zunstable-options", "--cfg", "docsrs"]
 all-features = true

crates/bevy_gizmos/macros/Cargo.toml

@@ -11,12 +11,17 @@ keywords = ["bevy"]
 [lib]
 proc-macro = true
 
-[lints]
-workspace = true
 
 [dependencies]
 bevy_macro_utils = { path = "../../bevy_macro_utils", version = "0.14.0-dev" }
 
 syn = "2.0"
 proc-macro2 = "1.0"
 quote = "1.0"
+
+[lints]
+workspace = true
+
+[package.metadata.docs.rs]
+rustdoc-args = ["-Zunstable-options", "--cfg", "docsrs"]
+all-features = true

crates/bevy_gizmos/macros/src/lib.rs

@@ -1,3 +1,5 @@
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+
 //! Derive implementations for `bevy_gizmos`.
 
 use bevy_macro_utils::BevyManifest;

crates/bevy_gizmos/src/lib.rs

@@ -1,3 +1,5 @@
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+
 //! This crate adds an immediate mode drawing api to Bevy for visual debugging.
 //!
 //! # Example
@@ -13,7 +15,6 @@
 //! ```
 //!
 //! See the documentation on [Gizmos](crate::gizmos::Gizmos) for more examples.
-#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 
 /// System set label for the systems handling the rendering of gizmos.
 #[derive(SystemSet, Clone, Debug, Hash, PartialEq, Eq)]

crates/bevy_gltf/Cargo.toml

@@ -60,4 +60,5 @@ smallvec = "1.11"
 workspace = true
 
 [package.metadata.docs.rs]
+rustdoc-args = ["-Zunstable-options", "--cfg", "docsrs"]
 all-features = true

crates/bevy_gltf/src/lib.rs

@@ -1,8 +1,9 @@
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+
 //! Plugin providing an [`AssetLoader`](bevy_asset::AssetLoader) and type definitions
 //! for loading glTF 2.0 (a standard 3D scene definition format) files in Bevy.
 //!
 //! The [glTF 2.0 specification](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html) defines the format of the glTF files.
-#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 
 #[cfg(feature = "bevy_animation")]
 use bevy_animation::AnimationClip;

crates/bevy_hierarchy/Cargo.toml

@@ -31,4 +31,5 @@ smallvec = { version = "1.11", features = ["union", "const_generics"] }
 workspace = true
 
 [package.metadata.docs.rs]
+rustdoc-args = ["-Zunstable-options", "--cfg", "docsrs"]
 all-features = true

crates/bevy_hierarchy/src/lib.rs

@@ -1,3 +1,5 @@
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+
 //! Parent-child relationships for Bevy entities.
 //!
 //! You should use the tools in this crate
@@ -44,7 +46,6 @@
 //! [plugin]: HierarchyPlugin
 //! [query extension methods]: HierarchyQueryExt
 //! [world]: BuildWorldChildren
-#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 
 mod components;
 pub use components::*;

crates/bevy_input/Cargo.toml

@@ -32,4 +32,5 @@ smol_str = "0.2"
 workspace = true
 
 [package.metadata.docs.rs]
+rustdoc-args = ["-Zunstable-options", "--cfg", "docsrs"]
 all-features = true

crates/bevy_input/src/lib.rs

@@ -1,9 +1,10 @@
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+
 //! Input functionality for the [Bevy game engine](https://bevyengine.org/).
 //!
 //! # Supported input devices
 //!
 //! `bevy` currently supports keyboard, mouse, gamepad, and touch inputs.
-#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 
 mod axis;
 mod button_input;

crates/bevy_internal/Cargo.toml

@@ -207,3 +207,7 @@ bevy_dev_tools = { path = "../bevy_dev_tools", optional = true, version = "0.14.
 
 [lints]
 workspace = true
+
+[package.metadata.docs.rs]
+rustdoc-args = ["-Zunstable-options", "--cfg", "docsrs"]
+all-features = true

crates/bevy_internal/src/lib.rs

@@ -1,3 +1,5 @@
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+
 //! This module is separated into its own crate to enable simple dynamic linking for Bevy, and should not be used directly
 
 /// `use bevy::prelude::*;` to import common components, bundles, and plugins.

crates/bevy_log/Cargo.toml

@@ -40,4 +40,5 @@ tracing-wasm = "0.2.1"
 workspace = true
 
 [package.metadata.docs.rs]
+rustdoc-args = ["-Zunstable-options", "--cfg", "docsrs"]
 all-features = true

crates/bevy_log/src/lib.rs

@@ -1,3 +1,5 @@
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+
 //! This crate provides logging functions and configuration for [Bevy](https://bevyengine.org)
 //! apps, and automatically configures platform specific log handlers (i.e. WASM or Android).
 //!
@@ -9,7 +11,6 @@
 //!
 //! For more fine-tuned control over logging behavior, set up the [`LogPlugin`] or
 //! `DefaultPlugins` during app initialization.
-#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 
 #[cfg(feature = "trace")]
 use std::panic;