Add links to doc items to the Unstable Book

[alercah]

Currently the Unstable Book has autogenerated library feature links:

rust/src/tools/unstable-book-gen/src/main.rs

Line 39 in 4a82c21

let lib_features_str = set_to_summary_str(&unstable_lib_features, "library-features");

but all they do is link to the tracking issue.

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

[jyn514]

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.

[Mark-Simulacrum]

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.

[jyn514]

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?

[jyn514]

Oh oof, another thing I found just now is that some library features are missing a page in the book at all. c_variadic, the example I used just now, has a language feature page but no library feature page. That definitely seems like something we should add a tidy check for.

[jyn514]

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:

• Fill out all the TODOs in the code (https://rust-lang.zulipchat.com/#narrow/stream/266220-rustdoc/topic/full.20path.20of.20item.20in.20json.20docs may be useful)
• Figure out how to parse a syn::Attribute
• Actually take that parsed data and use it to find library features that are undocumented

@rustbot label +E-medium +E-mentor

[albertlarsan68]

@rustbot claim

In a week or so, I will have some time to kill.

[albertlarsan68]

There are many library features that are undocumented, I now detect them (by panicking on file missing).
I will continue working on that, it is in #106681.