Generate links to definition in source code pages on docs.rs and dev-docs.bevyengine.org (#12965)

# Objective

- Fix issue #2611

## Solution

- Add `--generate-link-to-definition` to all the `rustdoc-args` arrays
in the `Cargo.toml`s (for docs.rs)
- Add `--generate-link-to-definition` to the `RUSTDOCFLAGS` environment
variable in the docs workflow (for dev-docs.bevyengine.org)
- Document all the workspace crates in the docs workflow (needed because
otherwise only the source code of the `bevy` package will be included,
making the argument useless)
- I think this also fixes #3662, since it fixes the bug on
dev-docs.bevyengine.org, while on docs.rs it has been fixed for a while
on their side.

---

## Changelog

- The source code viewer on docs.rs now includes links to the
definitions.

.github/workflows/docs.yml

@@ -58,8 +58,19 @@ jobs:
       - 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
+          RUSTDOCFLAGS: -Zunstable-options --cfg=docsrs --generate-link-to-definition
+        run: cargo doc \
+            -Zunstable-options \
+            -Zrustdoc-scrape-examples \
+            --all-features \
+            --workspace \
+            --no-deps \
+            --exclude ci \
+            --exclude errors \
+            --exclude bevy_mobile_example \
+            --exclude build-wasm-example \
+            --exclude build-templated-pages \
+            --exclude example-showcase
 
       #  This adds the following:
       #   - A top level redirect to the bevy crate documentation

Cargo.toml

@@ -3339,6 +3339,6 @@ lto = "fat"
 panic = "abort"
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true
 cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]

crates/bevy_a11y/Cargo.toml

@@ -20,5 +20,5 @@ accesskit = "0.16"
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_animation/Cargo.toml

@@ -42,5 +42,5 @@ uuid = { version = "1.7", features = ["v4"] }
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_app/Cargo.toml

@@ -38,5 +38,5 @@ console_error_panic_hook = "0.1.6"
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_asset/Cargo.toml

@@ -67,5 +67,5 @@ bevy_log = { path = "../bevy_log", version = "0.15.0-dev" }
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_asset/macros/Cargo.toml

@@ -22,5 +22,5 @@ quote = "1.0"
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_audio/Cargo.toml

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

crates/bevy_color/Cargo.toml

@@ -28,5 +28,5 @@ serialize = ["serde"]
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_core/Cargo.toml

@@ -39,5 +39,5 @@ serde_test = "1.0"
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_core_pipeline/Cargo.toml

@@ -45,5 +45,5 @@ thiserror = "1.0"
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_derive/Cargo.toml

@@ -21,5 +21,5 @@ syn = { version = "2.0", features = ["full"] }
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_dev_tools/Cargo.toml

@@ -46,5 +46,5 @@ ron = { version = "0.8.0", optional = true }
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_diagnostic/Cargo.toml

@@ -39,5 +39,5 @@ sysinfo = { version = "0.30.0", optional = true, default-features = false }
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_dylib/Cargo.toml

@@ -18,5 +18,5 @@ bevy_internal = { path = "../bevy_internal", version = "0.15.0-dev", default-fea
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_dynamic_plugin/Cargo.toml

@@ -20,5 +20,5 @@ thiserror = "1.0"
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_ecs/Cargo.toml

@@ -53,5 +53,5 @@ path = "examples/change_detection.rs"
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_ecs/macros/Cargo.toml

@@ -19,5 +19,5 @@ proc-macro2 = "1.0"
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_encase_derive/Cargo.toml

@@ -19,5 +19,5 @@ encase_derive_impl = "0.8"
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_gilrs/Cargo.toml

@@ -24,5 +24,5 @@ thiserror = "1.0"
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_gizmos/Cargo.toml

@@ -35,5 +35,5 @@ bytemuck = "1.0"
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_gizmos/macros/Cargo.toml

@@ -23,5 +23,5 @@ quote = "1.0"
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_gltf/Cargo.toml

@@ -67,5 +67,5 @@ bevy_log = { path = "../bevy_log", version = "0.15.0-dev" }
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_hierarchy/Cargo.toml

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

crates/bevy_input/Cargo.toml

@@ -43,5 +43,5 @@ smol_str = "0.2"
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_internal/Cargo.toml

@@ -244,5 +244,5 @@ bevy_winit = { path = "../bevy_winit", optional = true, version = "0.15.0-dev" }
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_log/Cargo.toml

@@ -40,5 +40,5 @@ tracing-wasm = "0.2.1"
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_macro_utils/Cargo.toml

@@ -20,5 +20,5 @@ proc-macro2 = "1.0"
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_math/Cargo.toml

@@ -57,5 +57,5 @@ rand = ["dep:rand", "dep:rand_distr", "glam/rand"]
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_mikktspace/Cargo.toml

@@ -25,5 +25,5 @@ name = "generate"
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_pbr/Cargo.toml

@@ -64,5 +64,5 @@ static_assertions = "1"
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_ptr/Cargo.toml

@@ -14,5 +14,5 @@ keywords = ["bevy", "no_std"]
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_reflect/Cargo.toml

@@ -57,5 +57,5 @@ required-features = ["documentation"]
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_reflect/derive/Cargo.toml

@@ -30,5 +30,5 @@ uuid = { version = "1.1", features = ["v4"] }
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_render/Cargo.toml

@@ -130,5 +130,5 @@ send_wrapper = "0.6.0"
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_render/macros/Cargo.toml

@@ -22,5 +22,5 @@ quote = "1.0"
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_scene/Cargo.toml

@@ -40,5 +40,5 @@ rmp-serde = "1.1"
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_sprite/Cargo.toml

@@ -41,5 +41,5 @@ radsort = "0.1"
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_tasks/Cargo.toml

@@ -30,5 +30,5 @@ web-time = { version = "1.1" }
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_text/Cargo.toml

@@ -42,5 +42,5 @@ approx = "0.5.1"
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_time/Cargo.toml

@@ -32,5 +32,5 @@ thiserror = "1.0"
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_transform/Cargo.toml

@@ -52,5 +52,5 @@ serialize = ["dep:serde", "bevy_math/serialize"]
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_ui/Cargo.toml

@@ -46,5 +46,5 @@ serialize = ["serde", "smallvec/serde"]
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_utils/Cargo.toml

@@ -29,5 +29,5 @@ getrandom = { version = "0.2.0", features = ["js"] }
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_utils/macros/Cargo.toml

@@ -18,5 +18,5 @@ proc-macro2 = "1.0"
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_window/Cargo.toml

@@ -32,5 +32,5 @@ smol_str = "0.2"
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

crates/bevy_winit/Cargo.toml

@@ -56,5 +56,5 @@ crossbeam-channel = "0.5"
 workspace = true
 
 [package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
+rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"]
 all-features = true

errors/Cargo.toml

@@ -10,7 +10,3 @@ bevy = { path = ".." }
 
 [lints]
 workspace = true
-
-[package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
-all-features = true

examples/mobile/Cargo.toml

@@ -35,7 +35,3 @@ label = "Bevy Example"
 
 [lints]
 workspace = true
-
-[package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
-all-features = true

tools/build-templated-pages/Cargo.toml

@@ -16,7 +16,3 @@ hashbrown = { version = "0.14", features = ["serde"] }
 
 [lints]
 workspace = true
-
-[package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
-all-features = true

tools/build-wasm-example/Cargo.toml

@@ -12,7 +12,3 @@ clap = { version = "4.0", features = ["derive"] }
 
 [lints]
 workspace = true
-
-[package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
-all-features = true

tools/ci/Cargo.toml

@@ -12,7 +12,3 @@ bitflags = "2.3"
 
 [lints]
 workspace = true
-
-[package.metadata.docs.rs]
-rustdoc-args = ["-Zunstable-options"]
-all-features = true

tools/example-showcase/Cargo.toml

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