Support rustdoc root-url feature

[ehuss]

Rustdoc has an unstable flag --extern-html-root-url which allows you to redirect external links to a different site. It might be useful if cargo exposed native support for this feature somehow so that it could automatically fill in all the flags. This could allow libstd links to go to your local copy of libstd downloaded by rustup instead of doc.rust-lang.org for better offline support. Or redirect dependency links to another site like docs.rs instead of building all dependency docs.

Currently you can use it like this:

RUSTDOCFLAGS="--extern-html-root-url \
    std=file://$(rustc --print sysroot)/share/doc/rust/html \
    -Z unstable-options" cargo doc

And you can add other sysroot crates like proc_macro.

Some design work needs to be done to figure out exactly how this works. Some things to consider:

• What if the user doesn't use rustup?
• What if the docs weren't downloaded by rustup?
• What if rustup's directory layout changes?
• How might this interact in a possible future where cargo manages sysroot or otherwise has more knowledge of it? How would cargo know which crates exist in the sysroot?
• How can the user enter specific mappings, such as to docs.rs or other sites? Would there be interaction with --no-deps?

I'm imagine there are many other questions to be resolved.

See #8104 for a detailed use case example.

cc @QuietMisdreavus

[yaahc]

Okay I want to take on this issue, because I've wanted this for literally ages.

Talking to @QuietMisdreavus, she said the key parts are

(1) figuring out whether the user has rustup installed
(2) figuring out whether the user has the rust-docs component installed via rustup
(3) providing the correct --extern-html-root-url flags to rustdoc

I figure finding rust-docs and rustup should be jobs for cargo and that this is probably where I should start.

The only code I see looking at rustup from cargo is for fingerprinting. I'm wondering if I should add a fn in util::config similar to config::rustdoc which calls into get_tool, except one which tries to resolve rustup.

Once we have verified we have rustup, the next step is to figure out if rust-docs (I'm assuming this is the local copy of the std docs) is installed, no idea how to do that yet.

And then from there it seems pretty easy to just wire all the args around so the proper flags get passed into rustdoc.

[yaahc]

Further discussion with @QuietMisdreavus has made it seem like it might be a bit simpler than I thought. I don't think we need to involve rustup at all. rustc gives us the sysroot which is all we need. So...

1. Look up the local sysroot for the current compiler
2. look for docs in sysroot/blahblahblah/. For this I'm not really sure what the best way is to verify that the std docs are actually there other than just a simple [ -d ./std ] style check.
3. gather all of these local extern html root url links and pass them to rustdoc
4. Gate all this behind a new hidden flag that requires -Z unstable-options or something like that until its eventually stabilized.

[Ekleog]

Just wanted to drop by and say a word of support for this issue, it'd be really great to be able to be able to have a single tab open when developing :) (wrt. #7071 I think ideally it'd be possible to have a way to add std to the search index, for local development purposes, but this can certainly come in a second step)