Cross-crate intra doc links to transitive dependencies are not getting interpreted

[dtolnay]

I am trying to reproduce why https://docs.rs/tracing-opentelemetry/0.18.0/tracing_opentelemetry/index.html#special-fields has a broken "span kinds" link. The rendered HTML has <a href="opentelemetry::trace::SpanKind">span kinds</a> which is obviously not what was intended.

According to https://docs.rs/crate/tracing-opentelemetry/0.18.0/builds/632715, the build ran using rustc 1.66.0-nightly (a37499ae6 2022-09-18). I attempted to reproduce the issue as follows:

$ rustup toolchain install nightly-2022-09-19
$ rustc +nightly-2022-09-19 --version  # exact same as docs.rs log
rustc 1.66.0-nightly (a37499ae6 2022-09-18)

$ curl -L https://crates.io/api/v1/crates/tracing-opentelemetry/0.18.0/download -o tracing-opentelemetry-0.18.0.tgz
$ tar tf tracing-opentelemetry-0.18.0.tgz
$ cd tracing-opentelemetry-0.18.0

$ RUSTDOCFLAGS='--cfg docsrs --cap-lints=warn' cargo +nightly-2022-09-19 doc --all-features --open
...
warning: unresolved link to `opentelemetry::trace::StatusCode`
   --> src/lib.rs:30:26
    |
30  | //! [span status codes]: opentelemetry::trace::StatusCode
    |                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ no item named `StatusCode` in module `trace`
    |
note: the lint level is defined here
   --> src/lib.rs:115:10
    |
115 |     deny(rustdoc::broken_intra_doc_links),
    |          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

warning: unresolved link to `MetricsSubscriber`
  --> src/lib.rs:81:32
   |
81 | //! - `metrics`: Enables the [`MetricsSubscriber`] type, a [subscriber] that
   |                                ^^^^^^^^^^^^^^^^^ no item named `MetricsSubscriber` in scope
   |
   = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`

warning: unresolved link to `tracing_subscriber::subscribe`
   --> src/lib.rs:100:19
    |
100 | //! [subscriber]: tracing_subscriber::subscribe
    |                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ no item named `subscribe` in module `tracing_subscriber`

warning: `tracing-opentelemetry` (lib doc) generated 3 warnings

I put --cfg docs.rs and --all-features based upon the crate's Cargo.toml: https://docs.rs/crate/tracing-opentelemetry/0.18.0/source/Cargo.toml

[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]

As you can see, it reproduces the warnings seen in the docs.rs log. However, the generated HTML has a correct link <a href="../opentelemetry_api/trace/span/enum.SpanKind.html">span kinds</a>.

Is docs.rs's build doing something that is materially different from this? In order to make the link work, is this a rustdoc bug or a docs.rs bug? If rustdoc is working correctly, what would need to change in docs.rs to support this kind of link?

cc: @chriskonstad

[dtolnay]

I guess this has something to do with the fact that opentelemetry::trace::SpanKind is a re-export from a different crate opentelemetry_api. I made the following attempts to mimic what docs.rs might be doing:

• RUSTDOCFLAGS='--cfg docsrs --cap-lints=warn -Zunstable-options --extern-html-root-url=opentelemetry=https://docs.rs/opentelemetry/0.18.0' cargo +nightly-2022-09-19 doc --all-features --open --no-deps

  • broken link <a href="opentelemetry::trace::SpanKind">span kinds</a>

• RUSTDOCFLAGS='--cfg docsrs --cap-lints=warn -Zunstable-options --extern-html-root-url=opentelemetry_api=https://docs.rs/opentelemetry_api/0.18.0' cargo +nightly-2022-09-19 doc --all-features --open --no-deps

  • correct link <a href="https://docs.rs/opentelemetry_api/0.18.0/opentelemetry_api/trace/span/enum.SpanKind.html">span kinds</a>

So this might still be either a rustdoc issue or a docs.rs issue:

1. Does docs.rs need to pass --extern-html-root-url for all transitive dependencies, not just direct dependencies?

2. If not, does rustdoc need to generate a link to https://docs.rs/opentelemetry/0.18.0/opentelemetry/trace/enum.SpanKind.html and allow the user's browser to follow the redirect to https://docs.rs/opentelemetry_api/0.18.0/opentelemetry_api/trace/span/enum.SpanKind.html?

[dtolnay]

Mentioning @GuillaumeGomez @notriddle since this sounds like a similar sort of situation to the ones described in https://blog.guillaume-gomez.fr/articles/2023-03-08+rustdoc+and+the+re-exports and rust-lang/rust#104292.

Assuming my "mimic what docs.rs might be doing" in #2081 (comment) is reasonably representative, if rustdoc in --no-deps mode is building the docs of crate A (tracing-opentelemetry) and has an intra doc link to opentelemetry::trace::SpanKind in crate B (opentelemetry) which is a re-export of the type opentelemetry_api::trace::SpanKind from crate C (opentelemetry_api), the following situations could occur:

1. If rustdoc has --extern-html-root-url=C=..., obviously it can just link to the correct place. This works today.

2. If rustdoc has --extern-html-root-url=B=... but not --extern-html-root-url=C=..., today it generates a broken link. Is it possible / would it be reasonable to generate a link to the correct path under B's docs which will perform the necessary redirect to C's docs?

3. If rustdoc has both --extern-html-root-url=B=... and --extern-html-root-url=C=..., which one should it prefer for this link?

[dtolnay]

rust-lang/rust#106011 might also be at play. 😿

[jyn514]

1. Does docs.rs need to pass --extern-html-root-url for all transitive dependencies, not just direct dependencies?

yes, this is the problem. see rust-lang/cargo#8296 (comment) (I think -Zrustdoc-map is only thing you were missing in the command you ran to reproduce this - in the future you can use https://github.com/rust-lang/docs.rs/tree/master/crates/metadata to reproduce the exact arguments).

[jyn514]

cc rust-lang/rust#42301

[jyn514]

Duplicate of #1588.