cargo doc only direct dependencies

[nixpulvis]

From #1529 I suggested the following

[...] but I'd like a way to have the docs generated for all of my direct dependencies, but not their dependencies. In fact I'd argue this should be the default behavior.

If I add a crate "bar" as a dependency of the crate I'm working on "foo", then I'd love to see both "foo" and "bar"s documentation. However, if "bar" needs "baz" I frankly couldn't care less, as that's the decision of "bar" and I shouldn't need to look up anything in "baz".

All this is to say, generate docs for dependencies in Cargo.toml, but not Cargo.lock.

[gkoz]

This seems to hit the "Shared vs. Internal Dependencies" weakness pointed out in a wildcard dependencies RFC comment. Do you perhaps want to hide the crates that are just implementation details, no matter whose dependencies they are?

[nixpulvis]

Yea that is even more ideal, in general is expect the docs generated to be "relevant" to a user of the crate. So internal crates can be ignored as well.

[atoav]

Maybe it would be even enough to just hide external dependencies from the side bar to remove visual and cognitive clutter?

[krooq]

My expectation (as a relatively new rust/cargo user) when running cargo doc is that doc would only be built for the crates in my Cargo.toml.
More often than not, transitive dependencies are more stable and well understood.
However the choice to have transitive would be good as sometimes I do want to dive that deep.

Just for context...
I ended up here after looking for a way to navigate crate src in vscode.

[ghost]

Just a workaround, you could use third-party tools like cargo-makedocs (crates.io / GitHub).

[dureuill]

Just a workaround, you could use third-party tools like cargo-makedocs (crates.io / GitHub).

I tried the workaround, but it looks like cargo doc --no-deps removes all intradoc links to external crates, even if they are added back using -p <crate-name>. Since this appears to be the mechanism used by cargo-makedocs, it breaks all intradoc links to external crates, too.

[weihanglo]

A workaround for documenting direct dependencies:

cargo tree --depth 1 -e normal --prefix none | cut -d' ' -f1 | xargs printf -- '-p %s\n' | xargs cargo doc --no-deps
# become `cargo doc --no-deps -p <crate1> -p <crate2> -p <crate2>…`

Labelled as E-medium as it is not really hard in terms of coding. Feeding direct dependencies to rustdoc is sufficient I believe, as the above workaround shows we can use --package flag to achieve that. However, the interaction with rust -Zrustdoc-map needs more design spaces. And may also consider #2644 for the consistency between each subcommand.

[mjovanc]

It would be very useful if I could use a flag to do this instead of a workaround.

[wez]

What I'd like is for the crates in my workspace to have docs generated for them, and for any other deps that are not in my workspace to be emitted with links to crates.io (assuming that rustdoc knows that the deps are hosted in that registry) as well as the main rust docs for the built-in types.

I don't believe that there is a solution for this currently; I'm open to hearing about workarounds that can achieve this!

EDIT: Oh, I can use --depth 0 with the cargo tree invocation shown above!

[ehuss]

What I'd like is for the crates in my workspace to have docs generated for them, and for any other deps that are not in my workspace to be emitted with links to crates.io (assuming that rustdoc knows that the deps are hosted in that registry) as well as the main rust docs for the built-in types.

I don't believe that there is a solution for this currently; I'm open to hearing about workarounds that can achieve this!

I believe this can be done with https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#rustdoc-map which can be configured to link to docs.rs

[epage]

As part of or after we get #6129, should we switch the behavior to document all of the public dependencies?