-
Notifications
You must be signed in to change notification settings - Fork 12.9k
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
Add links to doc items to the Unstable Book #103548
Comments
It turns out the documentation for library features is not actually autogenerated; only the summary page is autogenerated. So this isn't something we can do automatically. One thing we could try is having a tidy lint that requires a link to doc.rust-lang.org somewhere in each library-features/*.md file. That will be too much work to do all at once though, so it will need to happen a bit at a time. We have some precedent for that with the way tests are being moved out src/test/ui a bit at a time; it would be a good E-easy E-mentor issue. |
I'm not convinced that manual work here is worth it (even if enforced by tidy). It's likely that it would be relatively painful to put together those URLs, and difficult to actually enforce full consistency with the true section gated by the relevant feature gate. On the other hand, it seems plausible that this could be easily generated from rustdoc (either built-in or via JSON). I think if we can guarantee the results the value would be nice for e.g. libs-api stabilization reports. But probably tricky to get everything. |
Ok cool! That seems very doable :) here's a hacky prototype: ; jq '.index | to_entries[] | select(.value.attrs[] | contains("c_variadic")) | .value | select(.name != null) | .name' -C $(rustc --print sysroot)/share/doc/rust/json/core.json
"VaList"
"VaListImpl"
"VaArgSafe" Rustdoc JSON has some way of finding the path of an item in the crate root I can figure out, and from there I can write a hacky script to add it to all the existing docs, then enforce a more reliable tidy check to make sure it's being added to all new documentation too. Does that sound good? |
Oh oof, another thing I found just now is that some library features are missing a page in the book at all. |
Ok, I am not personally going to have time to follow up on this. Here's some WIP code that starts on parsing the JSON output of rustdoc: https://github.com/rust-lang/rust/compare/master...jyn514:rust:stability-checks?expand=1 The next steps are:
@rustbot label +E-medium +E-mentor |
@rustbot claim In a week or so, I will have some time to kill. |
There are many library features that are undocumented, I now detect them (by panicking on file missing). |
Currently the Unstable Book has autogenerated library feature links:
rust/src/tools/unstable-book-gen/src/main.rs
Line 39 in 4a82c21
It would be very helpful to have them link to all the individual library items gated behind each feature flag.
cc @jyn514 @alice-i-cecile
The text was updated successfully, but these errors were encountered: