feat: rebuild(-ish) rustdoc json for different version of same crates

[motorailgun]

View all comments

Fix #16291.

What does this PR try to resolve?

As discussed in the linked issue, cargo rustdoc --output-format=json doesn't rebuild for same crate name but with different versions. This is because current cargo implementation around rustdoc only specifies output paths/names by only its crate names, but not with version(hash) info.

This PR forces new layout for json output, and uplift the file into backward-compatible place.

How to test and review this PR?

• Can we consider just forcing new layout for --output-format=json? (and stop uplifting)
• Uplifting will always happen even if uplifted json is fresh, and/or new layout is manually specified. (could not figure out how to prevent); however it is just a copy operation if docs JSON are already built and fresh.

[rustbot]

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

Why was this reviewer chosen?

The reviewer was selected based on:

• Owners of files modified in this PR: @ehuss, @epage, @weihanglo
• @ehuss, @epage, @weihanglo expanded to ehuss, epage, weihanglo
• Random selection from ehuss, epage, weihanglo

[motorailgun]

Updated to use new directory layout.

[rustbot]

This PR was rebased onto a different master commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[motorailgun]

Note: updated PR message reflecting changes.

[weihanglo]

We don't need to clean up doc.json file for the new layout, as they are isolated by units.

That said, I do want to know how this would affect cargo clean --doc. We should at least track it in the tracking issue

View changes since the review

[motorailgun]

From my quick observation, doc.json file will escape normal cargo clean --doc operation? Will dig into tomorrow.

cargo/src/cargo/ops/cargo_clean.rs

Lines 88 to 100 in f4f977f

	if opts.doc {
	if !opts.spec.is_empty() {
	// FIXME: https://github.com/rust-lang/cargo/issues/8790
	// This should support the ability to clean specific packages
	// within the doc directory. It's a little tricky since it
	// needs to find all documentable targets, but also consider
	// the fact that target names might overlap with dependency
	// names and such.
	bail!("--doc cannot be used with -p");
	}
	// If the doc option is set, we just want to delete the doc directory.
	target_dir = target_dir.join("doc");
	clean_ctx.remove_paths(&[target_dir.into_path_unlocked()])?;

[weihanglo]

Tracking issue btw: #13283

Though I feel like we probably don't need to deal with cargo clean --doc. So the behavior doesn't need to be "cleaning anything related to artifacts."

--doc
    This option will cause cargo clean to remove only the doc directory in the target directory.

That makes me wonder -Zrustdoc-mergeable-info also doesn't need to support cargo clean.

@ranger-ross any thoughts?

[weihanglo]

I meant, we may leave it for future. No need to worry about it now