Summary

Original issue: #12266
Implementation: #15359 #15605
Documentation: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#rustdoc-depinfo

The -Z rustdoc-depinfo flag leverages rustdoc’s dep-info files to determine whether documentations are required to re-generate. This can be combined with -Z checksum-freshness to detect checksum changes rather than file mtime.

Testing instructions: #15370 (comment)

Unresolved Issues

Blockers:

• To generate the correct styled docs, Cargo needs to pass --emit=toolchain-shared-resources,invocation-specific,dep-info=<PATH> to rustdoc. We need to stabilize the required rustdoc emit types all at once.
  • Multiple uses of --emit=dep-info do different things in rustc and rustdoc rust#141664
  • feat(rustdoc): stabilize --emit flag rust#146220
• Rustdoc should track extra theme/ CSS files as part of the rebuild detection
  • Ensure external paths passed via flags end up in rustdoc depinfo rust#144600

Open design questions:

• Where should rustdoc dep-info be emitted to?
  • The current implementation is under the fingerprint directory, e.g., target/debug/.fingerprint/serde-12d29d32b3b8b38f/doc-lib-serde.d. This might not be a blocker because fingerprint is not a stable interface Cargo guarantees.

Future Extensions

About tracking issues

Tracking issues are used to record the overall progress of implementation.
They are also used as hubs connecting to other relevant issues, e.g., bugs or open design questions.
A tracking issue is however not meant for large scale discussion, questions, or bug reports about a feature.
Instead, open a dedicated issue for the specific matter and add the relevant feature gate label.