Clarify that cargo doc --no-deps is cumulative and won’t delete prev
#15800
+10
−0
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
rustbot
added
A-documenting-cargo-itself
ojuschugh1
force-pushed
the
document-cargo-doc-no-deps
branch
from
b5fbe40 to
465c2af
Compare
weihanglo
reviewed
Aug 3, 2025
src/doc/man/cargo-doc.md
Outdated
| @@ -31,6 +31,15 @@ option. | |||
|
|
|||
| {{#option "`--no-deps`" }} | |||
| Do not build documentation for dependencies. | |||
|
|
|||
| **Note:** Documentation is _cumulative_. If you’ve already run | |||
There was a problem hiding this comment.
The cumulative behavior is not specific to the --no-deps flag. I would personally prefer to seeing this in DESCRIPTION than here.
There was a problem hiding this comment.
Sure, I have added this information in DESCRIPTION.
src/doc/man/cargo-doc.md
Outdated
| old dependency docs. To remove them, you can either: | ||
|
|
||
| 1. Run `cargo clean --doc` before `cargo doc --no-deps`, or | ||
| 2. Manually delete the unwanted folders under `target/doc/`. |
There was a problem hiding this comment.
Why did this call out manually? Anything cargo clean --doc can't achieve?
There was a problem hiding this comment.
This has been fixed, thanks !
ojuschugh1
force-pushed
the
document-cargo-doc-no-deps
branch
3 times, most recently
from
892bd12 to
55cb10b
Compare
rustbot
removed
the
S-waiting-on-review
weihanglo
reviewed
Aug 4, 2025
src/doc/man/cargo-doc.md
Outdated
| old dependency docs. To remove them, you can either: | ||
|
|
||
| 1. Run `cargo clean --doc` before `cargo doc --no-deps`, or | ||
| 2. Manually delete the unwanted folders under `target/doc/`. |
src/doc/man/cargo-doc.md
Outdated
| simply prevent *rebuilding* those pages—they will remain until you | ||
| explicitly clean them up. | ||
|
|
||
| ### Removing old docs |
There was a problem hiding this comment.
I don't feel like "Remvoing old docs" requires its own paragraph. We should probably put less doc on this.
Perhaps in combination of the previous paragraph, we do this
Documentation generation is cumulative: existing doc files in the target directory are preserved across different
cargo docinvocations. To remove existing generated docs, pass--docto {{man "cargo-clean" 1}}.
ojuschugh1
force-pushed
the
document-cargo-doc-no-deps
branch
from
55cb10b to
330f1de
Compare
One test failed for docs so i am fixing it and then i will push the changes again. |
ojuschugh1
force-pushed
the
document-cargo-doc-no-deps
branch
2 times, most recently
from
4986b8f to
b29b82e
Compare
ojuschugh1
force-pushed
the
document-cargo-doc-no-deps
branch
from
b29b82e to
004fa29
Compare
ojuschugh1
force-pushed
the
document-cargo-doc-no-deps
branch
2 times, most recently
from
23e20fc to
7e44417
Compare
rustbot
added
the
S-waiting-on-review
weihanglo
approved these changes
Aug 5, 2025
There was a problem hiding this comment.
Normally I would suggest splitting the second commit (fixing lint error) into its own pull request, though it is too much a hassle here atm so going to merge it as-is. I would still encourage fixing unrelated errors separately in the future.
Thanks for the contribution anyway.
epage
pushed a commit
to epage/cargo
that referenced
this pull request
Aug 5, 2025
These were caught with the latest nightly This was pulled from rust-lang#15800
github-merge-queue bot
pushed a commit
that referenced
this pull request
Aug 5, 2025
### What does this PR try to resolve? Unblock CI ### How to test and review this PR? ### Notes These were caught with the latest nightly This was pulled from #15800
ojuschugh1
force-pushed
the
document-cargo-doc-no-deps
branch
from
1a6b1da to
17463fd
Compare
…d regenerated pages using cargo build-man and ran ./ci/validate-man.sh
ojuschugh1
force-pushed
the
document-cargo-doc-no-deps
branch
from
17463fd to
ff9a9c8
Compare
weihanglo
added
Command-doc
and removed
A-documenting-cargo-itself
weihanglo
changed the title
cargo doc --no-deps is cumulative and won’t delete prev issue #15728cargo doc --no-deps is cumulative and won’t delete prev
rustbot
removed
the
S-waiting-on-review
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What does this PR try to resolve?
clarifies that cargo doc --no-deps will not delete previously-built dependency docs, and points users to cargo clean --doc or manual deletion if they want a truly “fresh” doc set. This pr fixed #15728
How to test and review this PR?
No testing required.