rustdoc: `--no-deps` does not rebuild documentation

[connortsui20]

I noticed that when I run cargo doc --no-deps after I have already built documentation with dependencies, it does not leave out the dependencies. I feel like this is probably not intended behavior and looking online I can't find anything that says this is correct.

Reproduction Steps

Simply run cargo doc, and then run cargo doc --no-deps, and there is no difference.

Expected Outcome

I would have expected that the docs would be rebuilt to include no dependencies.

Actual Output

This behavior is not really intuitive because the similar --document-private-items flag does rebuild the documentation if the current version has a different setting.

Version

rustdoc 1.88.0 (6b00bc388 2025-06-23)

[fmease]

@rustbot transfer cargo

[weihanglo]

Thanks for the report!

Given cargo doc already built everything, and with --no-deps it is building a subset of without --no-deps, I feel like there is nothing requiring a rebuild. Do you have a minimal reproducible example showing what is stale and should rebuild?

[weihanglo]

I noticed that when I run cargo doc --no-deps after I have already built documentation with dependencies, it does not leave out the dependencies. I feel like this is probably not intended behavior and looking online I can't find anything that says this is correct.

It is mostly intended because Cargo keeps build artifacts from previous runs, so if not necessary, Cargo doesn't run rustdoc.

[connortsui20]

Given cargo doc already built everything, and with --no-deps it is building a subset of without --no-deps, I feel like there is nothing requiring a rebuild. Do you have a minimal reproducible example showing what is stale and should rebuild?

This is true, but like I said above this is not really consistent with the behavior of --document-private-items (with cargo doc). Turning that flag on and off will trigger a rebuild (even if turning it off just means that we're only keeping a subset of the docs that was already built).

As for my personal issue, it doesn't really make sense that I would ever want to run cargo doc with --no-deps and want to keep all of the dependencies documented...

I guess my point is that it seems a bit roundabout to require people to first run cargo clean --doc and then cargo doc --no-deps in order to clean their documentation of any dependency crates.

[epage]

--no-deps is a form of package selection. iirc cargo doc is cumulative when it comes documenting packages, allowing you to do a cargo doc and then alter just a cargo doc -p foo to only update that one piece of documentation.

While not directly discussing this, I believe the following are related to the fact that documentation is cumulative

• cargo doc in workspaces includes removed crates' documentation if their previously built documentation is still in target/doc #6783
• documentation building is sensitive to the order docs are generated #8487

Hmm, not seeing this cumulative behavior discussed in the [docs]https://doc.rust-lang.org/cargo/commands/cargo-doc.html), I wonder if we should put it there.

[connortsui20]

@epage Apologies, I seem to have missed those issues, thanks for the link!

I could just close this issue now, but I'm wondering if people would benefit from a more consolidated issue on how cargo doc is cumulative. To be honest, that seems very strange and very much at odds with Rust's tooling in general (I think I am in agreement with this comment: #6783 (comment), but I would add I am not a new user and am still confused by this 😆)

[weihanglo]

Hmm, not seeing this cumulative behavior discussed in the docs, I wonder if we should put it there.

Yeah I think we should at least document the behavior.