explicitly link to external ena docs

[lcnr]

we currently do not link to the docs of ena: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_infer/infer/struct.InferCtxtInner.html#method.const_unification_table

[rust-highfive]

r? @Mark-Simulacrum

(rust-highfive has picked a reviewer for you, use r? to override)

[jyn514]

r? @jyn514

@lcnr is there a reason you did this instead of -Zrustdoc-map? Using --extern-html-root-url directly means you have to pass it yourself for each dependency.

(As discussed on Zulip, this probably works for indexmap because it has a doc(html_root_url) attribute it sets.)

[Mark-Simulacrum]

Hm, maybe we should just remove the no-deps flag in rustc docs generation?

As far as I can tell, there's no real reason for that exclusion, so we can probably just drop that which would probably fix all these links?

[lcnr]

I've now tried -Zrustdoc-map but that didn't seem to fix my issue:

diff --git a/library/backtrace b/library/backtrace
--- a/library/backtrace
+++ b/library/backtrace
@@ -1 +1 @@
-Subproject commit 4f925f8d81dfa57067537217e501e1dff7433491
+Subproject commit 4f925f8d81dfa57067537217e501e1dff7433491-dirty
diff --git a/src/bootstrap/doc.rs b/src/bootstrap/doc.rs
index c8714117930..b12bd43ab29 100644
--- a/src/bootstrap/doc.rs
+++ b/src/bootstrap/doc.rs
@@ -590,10 +590,16 @@ fn run(self, builder: &Builder<'_>) {
         cargo.rustdocflag("-Znormalize-docs");
         cargo.rustdocflag("--show-type-layout");
@@ -590,10 +590,15 @@ fn run(self, builder: &Builder<'_>) {
         cargo.rustdocflag("-Znormalize-docs");
         cargo.rustdocflag("--show-type-layout");
         compile::rustc_cargo(builder, &mut cargo, target);
+
+        cargo.arg("-Zunstable-options");
         cargo.arg("-Zskip-rustdoc-fingerprint");
 
         // Only include compiler crates, no dependencies of those, such as `libc`.
+        // Do link to dependencies on `docs.rs` however using `rustdoc-map`.
         cargo.arg("--no-deps");
+        cargo.arg("-Zrustdoc-map");
+        cargo.arg(r#"--config=doc.extern-map.registries.crates-io="https://docs.rs""#);
 
         // Find dependencies for top level crates.
         let mut compiler_crates = HashSet::new();

with this ./x.py doc --open --stage 1 still doesn't link to ena

[jyn514]

Hmm ok - cargo is trying to pass the flags, I see --extern-html-root-url 'smallvec=https://docs.rs/smallvec/1.6.1/' --extern-html-root-url 'tracing=https://docs.rs/tracing/0.1.25/' in the command line. But ena is missing. I think the issue is rustc_infer doesn't depend directly on ena instead, it depends on rustc_data_structures which re-exports an ena module. @ehuss mentioned this in the tracking issue: rust-lang/cargo#8296

Decide if Cargo should pass mappings for transitive dependencies (currently it does not). This normally isn't an issue, but can arise for re-exports (see the alt_registry test for an example). I'm not sure if this is a bug in rustdoc or not (there is a large number of issues regarding reexports and rustdoc). Cargo could include these, but this would make the command-line length even longer. Not sure what to do here.

@ehuss what do you think about including the transitive dependencies in the command line? Would it help if rustc exposed a list of crates which have re-exported types?

[jyn514]

In the meantime, @lcnr I agree with Mark that just removing --no-deps is fine and should fix the links :)

[lcnr]

tried out the documentation with --no-deps removed and now understand why it was added 😅

we depend on enough crates that searching for things like hir, Expr or literal has a lot of non-rustc results which is pretty annoying 😅 I prefer either using --rustdoc-map - which seems to still be a bit incomplete - or explicitly whitelisting ena for now, which is what this PR is currently doing.

[jyn514]

Hmm, ok - I still am not in favor of special casing ena though, since there are probably a lot of other broken links we just haven't noticed yet. Could you add both -Zrustdoc-map and the --extern-html-root-url=ena=... that you have now? That should take care of the vast majority of these issues, and then we can add more special cases as necessary.

[jyn514]

Looks great, thanks!

@bors r+ rollup

[bors]

📌 Commit 03f9fe2 has been approved by jyn514