`cargo rustdoc` should build docs for dependencies

[tari]

The rustdoc subcommand currently only builds documentation for the specified crate, and none of its dependencies. This is different from the behavior of cargo rustc which builds all dependencies (though that is by necessity) and cargo doc which includes all dependencies.

When building for custom targets, it is necessary to use cargo rustdoc to pass -Lpath to allow it to find the system libraries such as libcore. This only documents one crate, however, so getting the same behavior as cargo doc requires multiple invocations of cargo rustdoc with some glue logic to find dependencies.

---

Alternate approach that would also fix my issue: accept a RUSTDOCFLAGS environment variable similar to how RUSTFLAGS is currently handled. This is a feasible solution if the current limited behavior of cargo rustdoc is desired.

[alexcrichton]

Yeah seems like we should build dependency documentation as well (unless --no-deps is passed). I'd also be fine accepting RUSTDOCFLAGS!

[lambda-fairy]

I'd love a RUSTDOCFLAGS option too -- while hacking on my project I was surprised that RUSTFLAGS doesn't affect invocations of rustdoc.

As a workaround, my Makefile creates a wrapper script that calls rustdoc with the appropriate arguments:

doc: $(all_deps)
    mkdir -p target
    printf '#!/bin/sh\nexec rustdoc $$@ -L $(libcore_dir)' > target/rustdoc
    chmod +x target/rustdoc
    RUSTDOC=target/rustdoc RUSTFLAGS='-L $(libcore_dir)' cargo doc --release --target=$(target)

[Ekleog]

I'll just allow myself to poke this issue, as it's been without a message for ~4 years :)

[epage]

We discussed this in the cargo team meeting today.

RUSTDOCFLAGS is listed as an alternative and support was added in #2794.

Another alternative to this is being able to specify multiple packages. This is being tracked in #15733.

Considering cargo doc is our higher level command to embody policy like "build docs of dependencies", we're inclined to leave this to the given workarounds. If there is a reason for us to re-evaluate this, let us know!