rustdoc and linking to stdlib docs

[eminence]

• Observation: Running rustup doc is great and works wonderfully.
• Observation: The docs hosted on rust-lang.org are Unix only. Windows-only types are no-where to be found.
• Observation: After running cargo doc and viewing local docs, any links to stdlib types are redirected to the rust-lang.org hosted docs, and so links to Windows-only types are 404 not found

Problem: How to view the correct version of stdlib docs?

For example, reading the docs for AsRawFd you see this:

This is only available on unix platforms and must be imported in order to call the method. Windows platforms have a corresponding AsRawHandle and AsRawSocket set of traits.

But if you try to search for AsRawSocket, there are no results, which is kinda frustrating.

So my first thought was: how to remove the frustration of Unix-only docs on rust-lang.org? I don't have a proposal for this yet.

But my second thought was this: If rustup knows the path to the stdlib docs, could this path be passed to rustdoc, so that rustdoc can use local stdlib docs, instead of rust-lang.org docs? This should be an optional mode, since a very common use case is to use rustdoc to generated docs to be hosted somewhere (like github pages), and in this case, linking to rust-lang.org docs would make more sense.

What do you all think?

[eminence]

Half dup of #1998

[QuietMisdreavus]

Update: Thanks to #43348, the Windows docs are now hosted on rust-lang.org, and https://doc.rust-lang.org/nightly/std/os/windows/io/trait.AsRawSocket.html is searchable and linkable.

However, the other half of the issue (about local cargo doc being able to link to std docs downloaded by rustup) is still valid, and something that's possible now. #51384 added a flag to rustdoc to override the URL set by a crate's own #![doc(html_root_url)], so a flag could be added to cargo to pass these flags to rustdoc when generating docs locally. @rust-lang/cargo, do you think this functionality would be desired?

[ehuss]

@QuietMisdreavus I think it sounds interesting. I opened an issue at rust-lang/cargo#6279 to track the feature request. Feel free to add to it or correct anything that I may have misinterpreted. The team is currently doing long-term planning and may be a little busy in the short term, and I'm not aware of anyone who would push it forward right now. But we can definitely talk about it more.

[ehuss]

There is now an experimental flag in cargo called -Zrustdoc-map that offers some config options for controlling where links go (rust-lang/cargo#8296). For linking directly to the local std docs, the following may be placed in any cargo config file:

[doc.extern-map]
std = "local"

More details in the docs: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#rustdoc-map

[jyn514]

Closing this in favor of rust-lang/cargo#8296, rustdoc can't do this on its own.