Skip to content

Rustdoc: Restore visibility of required components #18171

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Conversation

SpecificProtagonist
Copy link
Contributor

@SpecificProtagonist SpecificProtagonist commented Mar 6, 2025

Objective

Follow up on #18165 to make the list of a component's required components easily accessible again.

Alternative to #18169

This PR is stacked on top of #18165 and #17857, so review by looking at the changes in the last commit here if those aren't merged yet.

Solution

When using the rustdoc extensions (which also add trait tags), add the list of required components, if there are any, as a new section directly after the main doc comment. Fall back to the current behavior if there's an incompatible change to rustdoc's html format.

This could be extended to also show what components require the documented component.

Testing

Run

cargo build --package rustdoc-wrapper --release
cargo doc --config "build.rustdoc = \"target/release/rustdoc-wrapper\"" --workspace

Showcase

bevy required components

@SpecificProtagonist SpecificProtagonist added C-Docs An addition or correction to our documentation A-ECS Entities, components, systems, and events S-Needs-Review Needs reviewer attention (from anyone!) to move forward labels Mar 6, 2025
@alice-i-cecile alice-i-cecile added this to the 0.16 milestone Mar 6, 2025
@alice-i-cecile alice-i-cecile added the X-Controversial There is active debate or serious implications around merging this PR label Mar 6, 2025
@alice-i-cecile alice-i-cecile removed this from the 0.16 milestone Mar 6, 2025
@alice-i-cecile
Copy link
Member

I prefer #18169 because I don't particularly like #17857, and because I really like the backlinks there. Nominating to close, but please feel free to argue.

@alice-i-cecile alice-i-cecile added the S-Nominated-To-Close A triage team member thinks this PR or issue should be closed out. label Mar 7, 2025
@SpecificProtagonist
Copy link
Contributor Author

SpecificProtagonist commented Mar 7, 2025

I disagree with the reasoning: I don't like using rustdoc's html format to extract the information needed for trait tags and #17857 is prerequisite to not doing that; and I can add backlinks, to this PR as well if we go with this approach.

Edit: #18169 was closed.

@NthTensor
Copy link
Contributor

Since the alternative was closed, I think we need to move forward with this for 0.17

Thoughts @alice-i-cecile?

@mockersf
Copy link
Member

Still against #17857 and this PR on my side. We want to reduce custom work by upstreaming what we can to rustdoc, not pile on more things that would make it so custom it would be of no interest to the Rust community at large.

As far as I know they are still waiting on a proposal from us describing what we want from tags

@NthTensor
Copy link
Contributor

I'm a bit disappointed because the current doc format for required components is absolutely not discoverable and presents a real problem to new users. But I understand the maintainability concern here. Seems like we need prioritize working with the docs.rs team on this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-ECS Entities, components, systems, and events C-Docs An addition or correction to our documentation S-Needs-Review Needs reviewer attention (from anyone!) to move forward S-Nominated-To-Close A triage team member thinks this PR or issue should be closed out. X-Controversial There is active debate or serious implications around merging this PR
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants