rust-lang/wg-cargo-std-aware

`cargo doc -Zbuild-std` doesn't generate links to the standard library

Opened this issue · 5 comments

jyn514 commented

See for example https://docs.rs/gba/latest/gba/macro.include_aligned_bytes.html.

@Nemo157 and I think this is because std doesn't have html_root_url set and cargo doesn't treat it as coming from crates.io, so -Zrustdoc-map doesn't help. The fix is for cargo to internally pass -Zcrate-attr=doc(html_root_url=https://doc.rust-lang.org/stable/std), like bootstrap does: https://github.com/rust-lang/rust/blob/871b5952023139738f72eba235063575062bc2e9/src/bootstrap/compile.rs#L416-L419

ehuss commented

Just curious, which of these behaviors would you expect to be the default, and which would you like the option of using?

  1. Link to https://doc.rust-lang.org/<channel>/
  2. Link to local docs installed via rustup
  3. Generate documentation for std in the local target folder and link to it there (like it was any other dependency)
Lokathor commented

I'd expect docs.rs to use (1), I'm not sure about local docs. Maybe I'd still expect (1) by default?

jyn514 commented

Hmm. docs.rs uses --no-deps, so it needs 1 to at least be an option - i would be ok with manually passing --extern-html-root-url there if you don't want to support it in cargo.

I'd expect 3. to be the behavior without --no-deps. I think with no-deps I'd expect 2. to be the default with a fallback to 1. if rust-docs isn't installed.

  • 👍2
Lokathor commented

Since this is specifically for build-std, rust-src will always be installed (edit: or if someone is silly enough to try and doc a crate they couldn't build on that same machine, it seems fine to just error out)

Nemo157 commented

I think with no-deps I'd expect 2. to be the default with a fallback to 1. if rust-src isn't installed.

I assume this was meant to be rust-docs not rust-src.

  • 👍1