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

fef8352
Opened by David Tolnay at 2023-03-11 17:19:50

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.

selection_056

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.

  1. 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?

    Laurențiu Nicola at 2017-11-10 18:48:56

  2. 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?

    Laurențiu Nicola at 2017-11-15 17:31:30

  3. 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.

    Lily Mara at 2018-12-11 20:15:00

  4. It looks like rustdoc gained the ability to receive the flag from cargo: https://github.com/rust-lang/rust/pull/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?

    Adam Perry at 2020-07-02 15:42:25

  5. 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 https://github.com/rust-lang/cargo/issues/8296 instead.

    jyn at 2020-11-04 06:26:22

  6. 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:

    <pre> /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 <b>--crate-version 1.0.34</b> --cfg backtrace` Finished dev [unoptimized + debuginfo] target(s) in 1.05s </pre>

    David Tolnay at 2020-11-18 23:53:25

  7. 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.

    jyn at 2020-11-19 00:14:50

  8. 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: https://github.com/rust-lang/api-guidelines/pull/230#issuecomment-730034673.

    jyn at 2020-11-19 00:15:22

  9. @dtolnay had an interesting suggestion in https://github.com/rust-lang/docs.rs/issues/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 (https://github.com/rust-lang/rfcs/issues/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.

    jyn at 2023-03-11 17:19:29