Trait-based sections on docs.rs

[SpecificProtagonist]

Objective

Trait tags for core Bevy traits are shown on the doc page of individual items (#17758). However, they are not visible at a glance in listings, instead the individual pages must be visited.

Solution

Add individual listings for the core Bevy traits. Types in the module that implement them get moved there. If a type impls multiple of these traits, it appears in all relevant listings.

Unfortunately, fetching the linked items in JS to check which traits they implement, as is done for the pages of individual types, leads to a visible delay. Therefore the data about which tags each item has needs to be embedded in the page; this is done via a new tool that adds an invisible div to the module doc comment. This modification of the source code is only intended for generating the rustdoc output and should not be committed to main.

I haven't adjusted the publishing process yet – François turned off dirty repo state during publishes just three days ago :P
We could either allow it again or publish with a separate git tag like "v0.16.0-docs".

Blocked on #17857

As a followup PR it should be made easier for interested 3rd-party bevy crates to use this.

Alternatives

Keep items in existing sections but add trait tags in the form of icons (currently in the form of a single letter) in front of item names in listings, matching the colors of the existing tags (and with a hover text naming the trait). Using icons both provides an redundant information channel for accessibility and is compact.

This is implemented in commit 2d1f0d0 if you want to try it out.

Testing

Run the following:

cargo run -p embed-trait-info-in-source
RUSTDOCFLAGS="--html-after-content docs-rs/trait-tags.html --cfg docsrs" RUSTFLAGS="--cfg docsrs_dep" cargo doc --no-deps --workspace

---

Showcase

More examples

[alice-i-cecile]

I love the concept, but as @JMS55 says, the icon set isn't quite doing it for me. They're neither clear nor particularly pretty. Could we use single colored letters maybe?

[kristoff3r]

I really like the listings per core type, this is something I've wanted for ages!

The implementation having to change the source while building is unfortunate though. Allowing that makes it easier to do sneaky supply chain attacks, and some sandboxed build systems like Nix and Bazel mount the source directories as read-only. It would be better if the data can be added to the generated docs after they've been built instead.

[SpecificProtagonist]

The implementation having to change the source while building is unfortunate though.

Yup. I'd say a path forward would be to propose a change to docs.rs to allow postprocessing the html output.
In the mean time, we could either:

• publish the modified source, or
• add a build script or similar that is only active on docs.rs & dev-docs.bevyengine.org

[SpecificProtagonist]

I think I've found the solution:

• replace the JS implementation with a tool that calls rustdoc and then modifies the generated HTML
• set package.metadata.docs.rs.cargo-args to --config build.rustdoc=<path to the tool>