Skip to content

Clarify that cargo doc --no-deps is cumulative and won’t delete prev issue #15728 #15800

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.

Sign up for GitHub

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

Jump to bottom
Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Clarify that cargo doc --no-deps is cumulative and won’t delete prev issue #15728 #15800

wants to merge 2 commits into from

Conversation

ojuschugh1
Copy link
Contributor

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.

@rustbot
Copy link
Collaborator

rustbot commented Aug 3, 2025

r? @epage

rustbot has assigned @epage.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

@rustbot rustbot added A-documenting-cargo-itself Area: Cargo's documentation S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Aug 3, 2025
@ojuschugh1 ojuschugh1 force-pushed the document-cargo-doc-no-deps branch from b5fbe40 to 465c2af Compare August 3, 2025 11:28
@rustbot rustbot added the A-cli-help Area: built-in command-line help label Aug 3, 2025
weihanglo
weihanglo reviewed Aug 3, 2025
View reviewed changes
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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The cumulative behavior is not specific to the --no-deps flag. I would personally prefer to seeing this in DESCRIPTION than here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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/`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why did this call out manually? Anything cargo clean --doc can't achieve?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This hasn't been addressed.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This has been fixed, thanks !

@ojuschugh1 ojuschugh1 force-pushed the document-cargo-doc-no-deps branch 3 times, most recently from 892bd12 to 55cb10b Compare August 4, 2025 18:53
@ojuschugh1 ojuschugh1 marked this pull request as draft August 4, 2025 18:53
@rustbot rustbot removed the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Aug 4, 2025
weihanglo
weihanglo reviewed Aug 4, 2025
View reviewed changes
Copy link
Member

@weihanglo weihanglo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure why putting this in draft again. Ready for review?

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/`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This hasn't been addressed.

src/doc/man/cargo-doc.md Outdated
simply prevent *rebuilding* those pages—they will remain until you
explicitly clean them up.

### Removing old docs
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 doc invocations. To remove existing generated docs, pass --doc to {{man "cargo-clean" 1}}.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

@ojuschugh1 ojuschugh1 force-pushed the document-cargo-doc-no-deps branch from 55cb10b to 330f1de Compare August 4, 2025 19:27
@ojuschugh1
Copy link
Contributor Author

Not sure why putting this in draft again. Ready for review?

One test failed for docs so i am fixing it and then i will push the changes again.

@ojuschugh1 ojuschugh1 force-pushed the document-cargo-doc-no-deps branch 2 times, most recently from 4986b8f to b29b82e Compare August 4, 2025 19:52
@rustbot rustbot added the A-build-scripts Area: build.rs scripts label Aug 4, 2025
@ojuschugh1 ojuschugh1 force-pushed the document-cargo-doc-no-deps branch from b29b82e to 004fa29 Compare August 4, 2025 20:00
@rustbot rustbot added the A-configuration Area: cargo config files and env vars label Aug 4, 2025
@ojuschugh1 ojuschugh1 force-pushed the document-cargo-doc-no-deps branch from dfc71cd to 23e20fc Compare August 4, 2025 20:25
@ojuschugh1 ojuschugh1 force-pushed the document-cargo-doc-no-deps branch from 23e20fc to 7e44417 Compare August 4, 2025 20:48
@ojuschugh1 ojuschugh1 marked this pull request as ready for review August 4, 2025 21:12
@rustbot rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Aug 4, 2025
@ojuschugh1 ojuschugh1 requested a review from weihanglo August 4, 2025 21:12
weihanglo
weihanglo approved these changes Aug 5, 2025
View reviewed changes
Copy link
Member

@weihanglo weihanglo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

weihanglo
weihanglo requested changes Aug 5, 2025
View reviewed changes
Copy link
Member

@weihanglo weihanglo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Found some more stuff to change.

Given that, I would suggest doing this in a separate PR.

src/doc/man/cargo-doc.md
@@ -16,6 +16,8 @@ cargo-doc --- Build a package's documentation
Build the documentation for the local package and all dependencies. The output
is placed in `target/doc` in rustdoc's usual format.

**Note:** Documentation generation is cumulative: existing doc files in the target directory are preserved across different cargo doc invocations. To remove existing generated docs, pass `--doc` to {{man "cargo-clean" 1}}.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
**Note:** Documentation generation is cumulative: existing doc files in the target directory are preserved across different cargo doc invocations. To remove existing generated docs, pass `--doc` to {{man "cargo-clean" 1}}.
**Note:** Documentation generation is cumulative: existing doc files in the target directory are preserved across different `cargo doc` invocations. To remove existing generated docs, pass `--doc` to {{man "cargo-clean" 1}}.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, given the file wrap lines at 80 columns, could this follow?

epage pushed a commit to epage/cargo that referenced this pull request Aug 5, 2025
@ojuschugh1 @epage
docs(build-rs): Fix broken intra-doc links
c0c256b 
These were caught with the latest nightly

This was pulled from rust-lang#15800
@epage epage mentioned this pull request Aug 5, 2025
Merged
github-merge-queue bot pushed a commit that referenced this pull request Aug 5, 2025
@weihanglo
docs(build-rs): Fix broken intra-doc links (#15810)
c01efc8 
### 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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@weihanglo weihanglo weihanglo requested changes

Requested changes must be addressed to merge this pull request.

Assignees

@epage epage

Labels
A-build-scripts Area: build.rs scripts A-cli-help Area: built-in command-line help A-configuration Area: cargo config files and env vars A-documenting-cargo-itself Area: Cargo's documentation S-waiting-on-review Status: Awaiting review from the assignee but also interested parties.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

rustdoc: --no-deps does not rebuild documentation
4 participants
@ojuschugh1 @rustbot @weihanglo @epage