Trait tags on docs.rs

[SpecificProtagonist]

Objective

Bevy's ECS provides several core traits such as Component, SystemParam, etc that determine where a type can be used. When reading the docs, this currently requires scrolling down to and scanning the "Trait Implementations" section. Make these core traits more visible.

Solution

Add a color-coded labels below the type heading denoting the following types:

• Component
  • immutable components are labeled as such
• Resource
• Asset
• Event
• Plugin & PluginGroup
• ScheduleLabel & SystemSet
• SystemParam

As docs.rs does not provide an option for post-processing the html, these are added via JS with traits implementations being detected by scanning the DOM. Rustdoc's html output is unstable, which could potentially lead to this detection (or the adding of the labels) to break, however it only needs to work when a new release is deployed and falls back to the status quo of not displaying these labels.

Idea by JMS55, implementation by Jondolf (see https://github.com/Jondolf/bevy_docs_extension_demo/).

Testing

Run this in Bevy's root folder:

 RUSTDOCFLAGS="--html-after-content docs-rs/trait-tags.html --cfg docsrs_dep" RUSTFLAGS="--cfg docsrs_dep" cargo doc --no-deps -p <some_bevy_package>

---

Showcase

Check it out on docs.rs

Release Notes

On docs.rs, Bevy now displays labels indicating which core traits a type implements:

If you want to add these to your own crate, check out these instructions.

[alice-i-cecile]

I love the end result. I'll let others chime in on the impl though.

[BD103]

Changes look good! I'm not sure I like creating a new root-level folder, but there are no better alternatives right now. Thank you, this is really cool!

[SpecificProtagonist]

I'm not sure I like creating a new root-level folder, but there are no better alternatives right now.

I considered putting it in docs/, but that doesn't fit as it affects generated docs instead of being documentation like the rest of that folder.

Putting this in tools/ should make sense though, no?

[BD103]

I'm not sure I like creating a new root-level folder, but there are no better alternatives right now.

I considered putting it in docs/, but that doesn't fit as it affects generated docs instead of being documentation like the rest of that folder.

Putting this in tools/ should make sense though, no?

It should! In the future it may be worth combining a lot of the root folders we have into something like etc, but for now I'd be happy with either docs-rs or tools.

[SpecificProtagonist]

The entries in tools currently are automatically members of the cargo workspace, so I think I'll stay with docs-rs.

[mockersf]

could you add the new flags to https://github.com/bevyengine/bevy/blob/main/.github/workflows/docs.yml#L64?

[SpecificProtagonist]

could you add the new flags to https://github.com/bevyengine/bevy/blob/main/.github/workflows/docs.yml#L64?

Thanks, lost that change when splitting apart the PR.