diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 17ac22019e..8a04fadc94 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -59,7 +59,7 @@ jobs: env: # needs to be in sync with [package.metadata.docs.rs] RUSTFLAGS: --cfg docsrs_dep - RUSTDOCFLAGS: -Zunstable-options --cfg=docsrs --generate-link-to-definition + RUSTDOCFLAGS: -Zunstable-options --cfg=docsrs --generate-link-to-definition --html-after-content docs-rs/trait-tags.html run: | cargo doc \ -Zunstable-options \ diff --git a/Cargo.toml b/Cargo.toml index 383cb50aad..9db0b57510 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -4102,7 +4102,15 @@ panic = "abort" # for details on why this is needed. Since dependencies don't expect to be built # with `--cfg docsrs` (and thus fail to compile) we use a different cfg. rustc-args = ["--cfg", "docsrs_dep"] -rustdoc-args = ["-Zunstable-options", "--generate-link-to-definition"] +rustdoc-args = [ + "-Zunstable-options", + "--generate-link-to-definition", + # Embed tags to the top of documentation pages for common Bevy traits + # that are implemented by the current type, like `Component` or `Resource`. + # This makes it easier to see at a glance what types are used for. + "--html-after-content", + "docs-rs/trait-tags.html", +] all-features = true cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"] diff --git a/docs-rs/README.md b/docs-rs/README.md new file mode 100644 index 0000000000..5d9092b806 --- /dev/null +++ b/docs-rs/README.md @@ -0,0 +1,33 @@ +# Docs.rs Extensions + +This directory includes some templates and styling to extend and modify [rustdoc]'s output +for Bevy's documentation on [docs.rs]. Currently this consists of tags indicating core +`bevy_ecs` traits. + +## 3rd Party Crates + +To use in your own crate, first copy this folder into your project, +then add the following to your Cargo.toml: + +```toml +[package.metadata.docs.rs] +rustc-args = ["--cfg", "docsrs_dep"] +rustdoc-args = [ + "--cfg", "docsrs_dep", + "--html-after-content", "docs-rs/trait-tags.html", +] + +[lints.rust] +unexpected_cfgs = { check-cfg = ['cfg(docsrs_dep)'] } +``` + +## Local Testing + +Build the documentation with the extension enabled like this: + +```bash +RUSTDOCFLAGS="--html-after-content docs-rs/trait-tags.html --cfg docsrs_dep" RUSTFLAGS="--cfg docsrs_dep" cargo doc --no-deps --package +``` + +[rustdoc]: https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html +[docs.rs]: https://docs.rs diff --git a/docs-rs/trait-tags.html b/docs-rs/trait-tags.html new file mode 100644 index 0000000000..3f65362213 --- /dev/null +++ b/docs-rs/trait-tags.html @@ -0,0 +1,165 @@ + + + \ No newline at end of file