-
-
Notifications
You must be signed in to change notification settings - Fork 3.9k
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
Rustdoc: Restore visibility of required components #18171
Conversation
Since the alternative was closed, I think we need to move forward with this for 0.17 Thoughts @alice-i-cecile? |
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 |
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. |
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