Skip to content

Commit

Permalink
Generate links to definition in source code pages on docs.rs and dev-…
Browse files Browse the repository at this point in the history
…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.
  • Loading branch information
SkiFire13 authored Jul 29, 2024
1 parent 29e9f0a commit 71c5f1e
Show file tree
Hide file tree
Showing 53 changed files with 59 additions and 72 deletions.
15 changes: 13 additions & 2 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
2 changes: 1 addition & 1 deletion crates/bevy_a11y/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_animation/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_app/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_asset/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_asset/macros/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_audio/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_color/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_core/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_core_pipeline/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_derive/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_dev_tools/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_diagnostic/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_dylib/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_dynamic_plugin/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_ecs/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_ecs/macros/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_encase_derive/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_gilrs/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_gizmos/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_gizmos/macros/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_gltf/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_hierarchy/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_input/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_internal/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_log/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_macro_utils/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_math/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_mikktspace/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_pbr/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_ptr/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_reflect/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_reflect/derive/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_render/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_render/macros/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_scene/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_sprite/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_tasks/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_text/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_time/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_transform/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_ui/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_utils/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_utils/macros/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_window/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion crates/bevy_winit/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
4 changes: 0 additions & 4 deletions errors/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,3 @@ bevy = { path = ".." }

[lints]
workspace = true

[package.metadata.docs.rs]
rustdoc-args = ["-Zunstable-options"]
all-features = true
4 changes: 0 additions & 4 deletions examples/mobile/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,3 @@ label = "Bevy Example"

[lints]
workspace = true

[package.metadata.docs.rs]
rustdoc-args = ["-Zunstable-options"]
all-features = true
4 changes: 0 additions & 4 deletions tools/build-templated-pages/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,3 @@ hashbrown = { version = "0.14", features = ["serde"] }

[lints]
workspace = true

[package.metadata.docs.rs]
rustdoc-args = ["-Zunstable-options"]
all-features = true
4 changes: 0 additions & 4 deletions tools/build-wasm-example/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,3 @@ clap = { version = "4.0", features = ["derive"] }

[lints]
workspace = true

[package.metadata.docs.rs]
rustdoc-args = ["-Zunstable-options"]
all-features = true
4 changes: 0 additions & 4 deletions tools/ci/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,3 @@ bitflags = "2.3"

[lints]
workspace = true

[package.metadata.docs.rs]
rustdoc-args = ["-Zunstable-options"]
all-features = true
4 changes: 0 additions & 4 deletions tools/example-showcase/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,3 @@ regex = "1.10.5"

[lints]
workspace = true

[package.metadata.docs.rs]
rustdoc-args = ["-Zunstable-options"]
all-features = true

0 comments on commit 71c5f1e

Please sign in to comment.