Incremental cargo doc doesn't support [lib] path to parent

[ThierryBerger]

Problem

When running cargo doc incrementally on a project with a parent [lib] path:

[lib]
name = "crate1"
path = "../src/lib.rs"

edits to files are not detected, ending up in a previous doc version.

Steps

See https://github.com/Vrixyz/cargo_parent_path.

1. Run cargo doc --open.

Output is:

 Documenting crate1 v0.1.0 (/path/to/here/crate1)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.17s
     Opening /path/to/here/target/doc/crate1/index.html

2. Change some documentation in src/lib.rs (and save).

Run again cargo doc --open.

Output is:

    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.00s
     Opening /path/to/here/target/doc/crate1/index.html

But should be the same as before.

3. Notice the opened documentation still shows the previous content, where we would have expected it to show the updated content.

Possible Solution(s)

No response

Notes

My current workaround is to run cargo clean (with -p package in bigger projects to avoid too expensive recompilation.

This bug had been present for a long time (I don´t believe that's a regression).

I detected this while working on https://github.com/dimforge/parry and similar crates.

Version

cargo 1.83.0 (5ffbef321 2024-10-29)
release: 1.83.0
commit-hash: 5ffbef3211a8c378857905775a15c5b32a174d3b
commit-date: 2024-10-29
host: x86_64-unknown-linux-gnu
libgit2: 1.8.1 (sys:0.19.0 vendored)
libcurl: 8.9.0-DEV (sys:0.4.74+curl-8.9.0 vendored ssl:OpenSSL/1.1.1w)
ssl: OpenSSL 1.1.1w  11 Sep 2023
os: Pop!_OS 22.4.0 (jammy) [64-bit]

[Jondolf]

I have the same problem in Avian, which uses a similar project structure.

[krtab]

I've started looking at this a bit and may have a hint, I'll try to dig in more and release the assignment if I don't find anything.
@rustbot claim

[ehuss]

Thanks for the report! I'm going to close as a duplicate of #12266. Unfortunately, cargo does not have the ability to detect the set of files involved with rustdoc. We would need rustdoc to gain the ability to emit a dep-info file to know which files are involved. Currently cargo can only check files in the package's directory and assume any one of them could affect the documentation.

[weihanglo]

@Vrixyz have you tried the -Zrustdoc-depinfo unstable flag? Did it work well on your sides? It would be appreciated to have your feedback :)

[Jondolf]

@weihanglo I tried running cargo doc --no-deps -Z rustdoc-depinfo in Avian, and adding the flag indeed seems to fix it for me 😄

However, it causes another weird problem. Starting fresh with no existing target/doc, the generated static.files folder is empty. This is meant to include stuff like fonts, CSS files, and scripts, but since it's empty, I just get the docs with default browser styling and no interactivity beyond links.

Without the flag, it works like normal. Not sure if this is expected?

[weihanglo]

Thanks @Jondolf for the report! Posted an issue in #15604.

[weihanglo]

@Jondolf the fix is available in the latest nightly already. Thanks again for the help!