Auto merge of #51384 - QuietMisdreavus:extern-version, r=GuillaumeGomez

rustdoc: add flag to control the html_root_url of dependencies

The `--extern-html-root-url` flag in this PR allows one to override links to crates whose docs are not already available locally in the doc bundle. Docs.rs currently uses a version of this to make sure links to other crates go into that crate's docs.rs page. See the included test for intended use, but the idea is as follows:

Calling rustdoc with `--extern-html-root-url crate=https://some-url.com` will cause rustdoc to override links that point to that crate to instead be replaced with a link rooted at `https://some-url.com/`. (e.g. for docs.rs this would be `https://docs.rs/crate/0.1.0` or the like.) Cheekily, rustup could use these options to redirect links to std/core/etc to instead point to locally-downloaded docs, if it so desired.

Fixes https://github.com/rust-lang/rust/issues/19603

1 files changed, 15 insertions, 0 deletions

diff --git a/src/doc/rustdoc/src/unstable-features.md b/src/doc/rustdoc/src/unstable-features.md
index a91c2cd71cd..a23dbd30824 100644
--- a/src/doc/rustdoc/src/unstable-features.md
+++ b/src/doc/rustdoc/src/unstable-features.md
@@ -361,6 +361,21 @@ This flag allows rustdoc to treat your rust code as the given edition. It will c
 the given edition as well. As with `rustc`, the default edition that `rustdoc` will use is `2015`
 (the first edition).
 
+### `--extern-html-root-url`: control how rustdoc links to non-local crates
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc src/lib.rs -Z unstable-options --extern-html-root-url some-crate=https://example.com/some-crate/1.0.1
+```
+
+Ordinarily, when rustdoc wants to link to a type from a different crate, it looks in two places:
+docs that already exist in the output directory, or the `#![doc(doc_html_root)]` set in the other
+crate. However, if you want to link to docs that exist in neither of those places, you can use these
+flags to control that behavior. When the `--extern-html-root-url` flag is given with a name matching
+one of your dependencies, rustdoc use that URL for those docs. Keep in mind that if those docs exist
+in the output directory, those local docs will still override this flag.
+
 ### `-Z force-unstable-if-unmarked`
 
 Using this flag looks like this: