Skip to content

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

Merged
weihanglo merged 1 commit intorust-lang:masterfrom
ojuschugh1:document-cargo-doc-no-deps
Aug 15, 2025
Merged

Clarify that cargo doc --no-deps is cumulative and won’t delete prev#15800
weihanglo merged 1 commit intorust-lang:masterfrom
ojuschugh1:document-cargo-doc-no-deps

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
{{#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.

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
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?

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.

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 2 times, most recently 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
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.

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.

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 added a commit to ojuschugh1/cargo that referenced this pull request Aug 15, 2025
Fix all the broken intra-doc links

docs(build-rs): Fix broken intra-doc links

These were caught with the latest nightly

This was pulled from rust-lang#15800

chore(deps): update rust crate cargo_metadata to 0.21.0

docs: `-Zpackage-workspace` has been stabilized

chore: bump to 0.92.0

docs: update changelog for 1.90.0

Add test for multiple build scripts in different order

Preserve order of build scripts

Update semver tests for 1.89

This updates the tests where messages have changed in 1.89.

chore(deps): update msrv (1 version) to v1.89

chore: Bump versions

test(build-std): relax the thread name assertion

rust-lang/rust#115746 changed to print thread ID,
so we update accordingly.

chore(deps): update cargo-semver-checks to v0.43.0

docs(unstable): Link out to the Plumbing commands effort

This is intended to help people discover where to go to discuss plumbing
command efforts.

chore(deps): update compatible

add is_inherited method to InheritableDependency

add is_inherited method to InheritableField

Add unstable `-Zsection-timings` flag

Pass `--json=timings` to rustc when `--timings` and `-Zsection-timings` is enabled

Parse and store section timing events

Add section timing data to JSON `--timings` output

Make headers of the HTML `--timings` unit table dynamic

Add compilation sections to the HTML unit table

Duplicates of unknown_feature test

More helpful error for invalid cargo-features = []

test(package): Add test to verify package build cache behavior

fix(package): Fixed inconsistent build cache behavior during package verify

When running `cargo package` the verify the build cache
(target-dir/build-dir) will not be used and all dependencies will be
recompiled.

This is inconsistent as setting target dir (via `CARGO_TARGET_DIR` for
example) will cause `cargo package` to reuse the build cache.

This commit changes the default behavior to always use the build cache,
matching the behavior of having target-dir set.

chore(deps): update msrv (3 versions) to v1.87

chore: remove x86_64-apple-darwin from CI and tests

RFC 3841 has merged, and x86_64-apple-darwin will be demoted to tier-2
in 1.90.0. In Cargo we usually run test against tier-1 platforms, so
x86_64-apple-darwin should be removed.
Also, that target platform is often the slowest one in CI,
we are happy to remove it to save us a couple of minutes.

https://rust-lang.github.io/rfcs/3841-demote-x86_64-apple-darwin.html

chore(deps): bump slab from 0.4.10 to 0.4.11

Bumps [slab](https://github.com/tokio-rs/slab) from 0.4.10 to 0.4.11.
- [Release notes](https://github.com/tokio-rs/slab/releases)
- [Changelog](https://github.com/tokio-rs/slab/blob/master/CHANGELOG.md)
- [Commits](tokio-rs/slab@v0.4.10...v0.4.11)

---
updated-dependencies:
- dependency-name: slab
  dependency-version: 0.4.11
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <support@github.com>

refactor: make resolve features public

feat(build-dir): Stabilize build-dir

docs: Formatting and cross-linking to build-dir/target-dir docs

Update src/doc/man/cargo-doc.md as per the feedback recieved

regenerated pages using cargo build-man and ran ./ci/validate-man.sh and sync branch with master branch
@ojuschugh1 ojuschugh1 force-pushed the document-cargo-doc-no-deps branch from 1a6b1da to 17463fd Compare August 15, 2025 19:23
…d regenerated pages using cargo build-man and ran ./ci/validate-man.sh
@ojuschugh1 ojuschugh1 force-pushed the document-cargo-doc-no-deps branch from 17463fd to ff9a9c8 Compare August 15, 2025 19:31
@weihanglo weihanglo added Command-doc and removed A-documenting-cargo-itself Area: Cargo's documentation A-configuration Area: cargo config files and env vars Command-clean Command-metadata A-interacts-with-crates.io Area: interaction with registries A-build-execution Area: anything dealing with executing the compiler Command-package A-workspaces Area: workspaces A-build-scripts Area: build.rs scripts A-dependency-resolution Area: dependency resolution and the resolver A-console-output Area: Terminal output, colors, progress bar, etc. A-manifest Area: Cargo.toml issues A-testing-cargo-itself Area: cargo's tests A-timings Area: timings A-features2 Area: issues specifically related to the v2 feature resolver A-unstable Area: nightly unstable support A-credential-provider Area: credential provider for storing and retreiving credentials A-infrastructure Area: infrastructure around the cargo repo, ci, releases, etc. labels Aug 15, 2025
@weihanglo weihanglo changed the title Clarify that cargo doc --no-deps is cumulative and won’t delete prev issue #15728 Clarify that cargo doc --no-deps is cumulative and won’t delete prev Aug 15, 2025
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.

Thanks!

@weihanglo weihanglo enabled auto-merge August 15, 2025 19:41
@weihanglo weihanglo added this pull request to the merge queue Aug 15, 2025
Merged via the queue into rust-lang:master with commit d1bbe63 Aug 15, 2025
23 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

A-cli-help Area: built-in command-line help Command-doc

Projects

None yet

Development

Successfully merging this pull request may close these issues.

rustdoc: --no-deps does not rebuild documentation

4 participants