Add experimental feature to link against local copy of std from cargo doc --open

[yaahc]

related to #6279

[rust-highfive]

r? @ehuss

(rust_highfive has picked a reviewer for you, use r? to override)

[QuietMisdreavus]

The interaction with rustdoc seems fine to me. I'll leave the proper review to Cargo-team people, though.

[ehuss]

Thanks for helping to move this along! This isn't quite the direction I was thinking of though, and doesn't close 6279. I'd prefer to lay out a plan for how it will work overall before jumping into adding new flags.

There are a variety of cases that I'd like to see cargo cover for mapping dependencies:

• Setting sysroot to local file (this PR).
  • How does this work with package managers? Do they install docs outside of sysroot?
• Setting dependencies to the local target (the current behavior).
• Setting dependencies to docs.rs.
  • How would that work with patched/replaced dependencies?
• Setting dependencies to some other website.
• Setting dependencies to some global shared folder.

I haven't thought about it much (hence the "needs design" part). I'm not sure if this is the kind of thing that should be defined in .cargo/config, or using command-line flags, or both.

[bors]

☔ The latest upstream changes (presumably #7185) made this pull request unmergeable. Please resolve the merge conflicts.

[yaahc]

Dumping some relevant info here from a recent twitter convo (https://twitter.com/yaahc_/status/1159014222031806465?s=20)

https://deterministic.space/serve-archived-static-files-over-http.html

from @killercup

[yaahc]

• Setting sysroot to local file (this PR).
  • How does this work with package managers? Do they install docs outside of sysroot?

Even with this part I don't feel like this PR fully addresses the problems. It makes crosslinking work but the two docs still act like otherwise unrelated webpages. I'd really like to see the search bar resolve items from both the locally generated crate / dependency docs and the std / core docs, not just have local items searchable but have clickable links to std/core items in the local doc pages.

I don't know how best to accomplish this though, particularly when you start tossing in other dependency mappings like to docs.rs. My expectation is that this would have to be accomplished via changes to rustdoc and even then I'm not sure all the information is there without having a local copy of std/core to look at. @QuietMisdreavus lmk what you think

• Setting dependencies to the local target (the current behavior).

I don't think this is the current behavior, my understanding is that we always set std / core links to the nightly docs on rust-lang.org https://doc.rust-lang.org/nightly/

[QuietMisdreavus]

I'd really like to see the search bar resolve items from both the locally generated crate / dependency docs and the std / core docs

I don't see a way to make this feasible without somehow embedding the search index from std and friends into everyone's search index, every time we ever generate docs. This would also severely clutter up the search index for regular crates who wouldn't want std to be searchable from their crate.

I could see it with a new flag to rustdoc, but making people add that manually seems like it would make it get less use. @rust-lang/rustdoc What do you think?

[GuillaumeGomez]

Seems like a bad idea (to add into the search-index). However, linking to local std types seems like a nice thing.

[yaahc]

@GuillaumeGomez when you say linking to local std types do you basically mean what's accomplished by this change? This already makes the std links in the docs point to the local copy of the std docs.

@QuietMisdreavus new flag sounds fine to me, I'm okay with it not being the default if most people wouldn't want it, who knows, maybe after using it I'll realize it was really a bad idea and not like the clutter either.

[GuillaumeGomez]

@yaahc: Yep and I approve it.

[yaahc]

ooh. cool 😅

[yaahc]

I'm gonna close this because I doubt I'll be able to get around to this any time soon, but if someone else wants to come along and pick up where I left off they're more than welcome to.