Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

cargo doc only direct dependencies #2025

Open
nixpulvis opened this issue Oct 5, 2015 · 11 comments
Open

cargo doc only direct dependencies #2025

nixpulvis opened this issue Oct 5, 2015 · 11 comments
Labels
Command-doc E-medium Experience: Medium S-needs-design Status: Needs someone to work further on the design for the feature or fix. NOT YET accepted.

Comments

@nixpulvis
Copy link

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
Copy link
Contributor

gkoz commented Oct 19, 2015

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
Copy link
Author

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
Copy link

atoav commented Mar 6, 2019

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

@krooq
Copy link

krooq commented Apr 18, 2020

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
Copy link

ghost commented Apr 18, 2020

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

@dureuill
Copy link

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 weihanglo added S-needs-design Status: Needs someone to work further on the design for the feature or fix. NOT YET accepted. E-medium Experience: Medium labels May 14, 2023
@weihanglo
Copy link
Member

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
Copy link

mjovanc commented Aug 8, 2023

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

@wez
Copy link

wez commented Sep 14, 2023

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
Copy link
Contributor

ehuss commented Sep 16, 2023

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
Copy link
Contributor

epage commented Sep 30, 2023

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

kezhuw added a commit to kezhuw/async-select that referenced this issue May 10, 2024
`#[cfg(doc)]` could change the interface and thus fail the build.

Refs:
 * rust-lang/cargo#8811
 * rust-lang/cargo#2025

changelog: changed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Command-doc E-medium Experience: Medium S-needs-design Status: Needs someone to work further on the design for the feature or fix. NOT YET accepted.
Projects
None yet
Development

No branches or pull requests