Link no-deps documentation with no html_root_url to docs.rs by default

[dtolnay]

As of Rust 1.19.0-nightly, documenting a crate with cargo doc --no-deps will link to the html_root_url of any dependencies that have one set, and other dependencies will not be linked.

In the screenshot, the crate providing HasHtmlRootUrl has an html_root_url so the type is linked. The crate providing NoHtmlRootUrl does not have an html_root_url so the type is not linked.

Linking NoHtmlRootUrl to docs.rs would be a reasonable fallback.

[lnicola]

rustdoc can't check (presumably) that the crate really exists on docs.rs. Would it be reasonable to simply link to a page that might 404?

[lnicola]

I tried to look into this, but I couldn't figure out how to get the crate versions. The best I managed to do was linking to https://docs.rs/crate/*/crate, which loads the latest version (I assume). Of course, it won't work if the crate is not published, or if the versions are different.

Any other ideas?

[lily-mara]

It seems like possibly, rustdoc could get the version information from the Cargo.toml of the package, and make a request to https://docs.rs/crate/version/crate, and if it comes back with a 200, include a docs.rs link.

[anp]

It looks like rustdoc gained the ability to receive the flag from cargo: #51384, which I think would be the API to use. There's been some recent progress by @ehuss on letting cargo configure rustdoc more granularly, perhaps there's a solution in that direction?

[jyn514]

I tried to look into this, but I couldn't figure out how to get the crate versions. The best I managed to do was linking to https://docs.rs/crate/*/crate, which loads the latest version (I assume). Of course, it won't work if the crate is not published, or if the versions are different.

Any other ideas?

Rustdoc does not have access to the version of the crate, only the crate name. 'versions' are a cargo concept and the rust compiler/rustdoc don't know about them.

It seems like possibly, rustdoc could get the version information from the Cargo.toml of the package, and make a request to https://docs.rs/crate/version/crate, and if it comes back with a 200, include a docs.rs link.

I don't like rustdoc making network requests or having knowledge of cargo. You should be able to use rustdoc standalone, without internet access or a Cargo.toml.

With both of those things in mind, I think it makes more sense to delegate this to rust-lang/cargo#8296 instead.

[dtolnay]

Rustdoc does not have access to the version of the crate, only the crate name. 'versions' are a cargo concept and the rust compiler/rustdoc don't know about them.

Rustdoc does have access to the version -- it's passed in the --crate-version flag:

/git/anyhow$ cargo doc --verbose
   Compiling anyhow v1.0.34 (/git/anyhow)
     Running `rustc --crate-name build_script_build --edition=2018 build.rs --error-format=json --json=diagnostic-rendered-ansi --crate-type bin --emit=dep-info,link -C embed-bitcode=no -C debuginfo=2 --cfg 'feature="default"' --cfg 'feature="std"' -C metadata=3bb41a976db3e451 -C extra-filename=-3bb41a976db3e451 --out-dir /git/anyhow/target/debug/build/anyhow-3bb41a976db3e451 -C incremental=/git/anyhow/target/debug/incremental -L dependency=/git/anyhow/target/debug/deps`
     Running `/git/anyhow/target/debug/build/anyhow-3bb41a976db3e451/build-script-build`
 Documenting anyhow v1.0.34 (/git/anyhow)
     Running `rustdoc --edition=2018 --crate-type lib --crate-name anyhow src/lib.rs
              -o /git/anyhow/target/doc --cfg 'feature="default"' --cfg 'feature="std"'
              --error-format=json --json=diagnostic-rendered-ansi -L dependency=/git/anyhow/target/debug/deps
              --crate-version 1.0.34 --cfg backtrace`
    Finished dev [unoptimized + debuginfo] target(s) in 1.05s

[jyn514]

Oh oops! This does make sense to add then I think.

rustdoc can't check (presumably) that the crate really exists on docs.rs. Would it be reasonable to simply link to a page that might 404?

That seems reasonable to me - either that or it could omit the version to get the latest that succeeded (but that would still break if no builds have succeeded). I'm still opposed to rustdoc making network requests though.

[jyn514]

Note the other reason I changed my mind on this is that there are build systems other than cargo that neither have a shared target directory nor use nightly: rust-lang/api-guidelines#230 (comment).

[jyn514]

@dtolnay had an interesting suggestion in rust-lang/docs.rs#2081:

---

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?

---

I think doing 2. is reasonable. 3. is not something rustdoc can do correctly without more information from the doc author (rust-lang/rfcs#3011); it can default to "the crate where the item is defined", but not anything smarter, and "where the item is defined" is sometimes the wrong heuristic.