feat(rustdoc): stabilize `--emit` flag by weihanglo · Pull Request #146220 · rust-lang/rust (original) (raw)

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.

By clicking “Sign up for GitHub”, you agree to our terms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Conversation

This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters

[ Show hidden characters]({{ revealButtonHref }})

TODO: stabilization report?

r? rustdoc

rustbot added S-waiting-on-author

Status: This is awaiting some action (such as code changes or more information) from the author.

T-rustdoc

Relevant to the rustdoc team, which will review and decide on the PR/issue.

labels

Sep 5, 2025

Questions:

Do we want to stabilize also unversioned-shared-resources option? It currently does nothing AFAIK.
Do we want a stabilization report?
How many details do we want to put in doc?

cc @aDotInTheVoid since you've involved in the PR removing the last blocker :)

rustbot added S-waiting-on-review

Status: Awaiting review from the assignee but also interested parties.

and removed S-waiting-on-author

Status: This is awaiting some action (such as code changes or more information) from the author.

labels

Sep 24, 2025

fmease added the needs-fcp

This change is insta-stable, or significant enough to need a team FCP to proceed.

label

Oct 13, 2025

We discussed on today's rustdoc meeting. Before going any further, we will investigate exactly what each --emit option does exactly to have a clearer picture of what's actually needed and also to add missing documentation.

We discussed on today's rustdoc meeting. Before going any further, we will investigate exactly what each --emit option does exactly to have a clearer picture of what's actually needed and also to add missing documentation.

Thanks for it!

This PR contains a doc based on my understanding and the history of these options, but I am not 100% sure if that is correct

This comment has been minimized.

I haven't read this yet but here are probably some very important and relevant considerations: #83784.

For the use case in Cargo, we actually don't need anything other than dep-info. The originak ask was here: #t-rustdoc > Plan to stabilize `--emit=dep-info[=path]` @ 💬:

One thing that might be a blocker: rust-lang/cargo#15605

Do we want to stabilize the --emit flag with all the emit types, or just dep-info? At this moment it is required for cargo to pass --emit=toolchain-shared-resources,invocation-specific,dep-info=<PATH> in order to make the generated doc look good and styled.

I guess one way forward is that rustdoc provides an extra emit type, say, default. So that cargo can run --emit=default,dep-info=/path/to/foo.d without even considering those other options. And in rustdoc documentation we can state that the default emit type is whatever the default emits rustdoc is doing. Pretty much like --remap-path-scope=all:

all - an alias for all of the above, also equivalent to supplying only --remap-path-prefix without --remap-path-scope.

ojeda mentioned this pull request

Oct 26, 2025

26 tasks

notriddle added a commit to notriddle/rust that referenced this pull request

Oct 27, 2025

This option hasn't done anything for a long time, and can be removed. I've kept a shim in place to avoid breaking docs.rs, but the option no longer does anything.

Using git-blame, I tracked this option down to f77ebd4, the commit that introduced EmitType in the first place. It was used with SharedResource::Unversioned, which no longer exists since f9e1f6f removed them.

Part of rust-lang#146220

I've opened #148180, a follow-up that removes the no-op unversioned-shared-resources, which hasn't done anything ever since we switched to using hashes for cache busting.

notriddle added a commit to notriddle/rust that referenced this pull request

Oct 27, 2025

This option hasn't done anything for a long time, and can be removed. I've kept a shim in place to avoid breaking docs.rs, but the option no longer does anything.

CC rust-lang#146220 Part of rust-lang#83784

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.

notriddle added a commit to notriddle/rust that referenced this pull request

Oct 28, 2025

This option hasn't done anything for a long time, and can be removed. I've kept a shim in place to avoid breaking docs.rs, but the option no longer does anything.

CC rust-lang#146220 Part of rust-lang#83784

matthiaskrgr added a commit to matthiaskrgr/rust that referenced this pull request

Oct 28, 2025

…rces, r=GuillaumeGomez

rustdoc: remove --emit=unversioned-shared-resources

This option hasn't done anything for a long time, and can be removed. I've kept a shim in place to avoid breaking docs.rs, but the option no longer does anything.

CC rust-lang#146220 Part of rust-lang#83784

rust-timer added a commit that referenced this pull request

Oct 28, 2025

Rollup merge of #148180 - notriddle:unversioned-shared-resources, r=GuillaumeGomez

rustdoc: remove --emit=unversioned-shared-resources

This option hasn't done anything for a long time, and can be removed. I've kept a shim in place to avoid breaking docs.rs, but the option no longer does anything.

CC #146220 Part of #83784

Choose a reason for hiding this comment

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

GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this pull request

Oct 30, 2025