Skip to content

feat(rustdoc): stabilize --emit flag #146220

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.

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

feat(rustdoc): stabilize --emit flag #146220

wants to merge 1 commit into from

Conversation

@weihanglo
Copy link
Member

@weihanglo weihanglo commented Sep 5, 2025

TODO: stabilization report?

r? rustdoc

@rustbot 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
@weihanglo
Copy link
Member Author

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

@weihanglo
Copy link
Member Author

weihanglo commented Sep 11, 2025

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

@weihanglo weihanglo marked this pull request as ready for review September 24, 2025 19:21
@rustbot 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 fmease added the needs-fcp This change is insta-stable, or significant enough to need a team FCP to proceed. label Oct 13, 2025
fmease
fmease reviewed Oct 13, 2025
View reviewed changes
@notriddle notriddle self-assigned this Oct 13, 2025
@GuillaumeGomez
Copy link
Member

GuillaumeGomez commented 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.

@fmease fmease mentioned this pull request Oct 13, 2025
Closed
@weihanglo
Copy link
Member Author

weihanglo commented 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.

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

@rustbot

This comment has been minimized.

Sign in to view
@weihanglo weihanglo mentioned this pull request Oct 25, 2025
Merged
@fmease fmease mentioned this pull request Oct 25, 2025
Open
3 tasks
@fmease
Copy link
Member

fmease commented Oct 25, 2025 •
edited
Loading

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

@weihanglo
Copy link
Member Author

weihanglo commented Oct 25, 2025

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 ojeda mentioned this pull request Oct 26, 2025
Open
25 tasks
notriddle added a commit to notriddle/rust that referenced this pull request Oct 27, 2025
@notriddle
rustdoc: remove --emit=unversioned-shared-resources
f3ebb35 
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
@notriddle notriddle mentioned this pull request Oct 27, 2025
Merged
@notriddle
Copy link
Contributor

notriddle commented Oct 27, 2025

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
@notriddle
rustdoc: remove --emit=unversioned-shared-resources
87c8068 
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.

CC rust-lang#146220
Part of rust-lang#83784
@rustbot
Copy link
Collaborator

rustbot commented Oct 27, 2025

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
@notriddle
rustdoc: remove --emit=unversioned-shared-resources
fe3490c 
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.

CC rust-lang#146220
Part of rust-lang#83784
matthiaskrgr added a commit to matthiaskrgr/rust that referenced this pull request Oct 28, 2025
@matthiaskrgr
Rollup merge of rust-lang#148180 - notriddle:unversioned-shared-resou…
71c4c89 
…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.

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.

CC rust-lang#146220
Part of rust-lang#83784
rust-timer added a commit that referenced this pull request Oct 28, 2025
@rust-timer
Unrolled build for #148180
7c423db 
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.

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.

CC #146220
Part of #83784
weihanglo
weihanglo commented Oct 29, 2025
View reviewed changes
Copy link
Member Author

@weihanglo weihanglo left a comment •
edited by rustbot
Loading

Choose a reason for hiding this comment

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

This PR has updated and removed the unversioned-shared-resources option, which was removed in #148180

View changes since this review

@notriddle notriddle mentioned this pull request Oct 29, 2025
Merged
GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this pull request Oct 30, 2025
@GuillaumeGomez
Rollup merge of rust-lang#148268 - notriddle:emit-scraped-examples, r…
6e52fb1 
…=GuillaumeGomez

rustdoc: fix `--emit=dep-info` on scraped examples

Makes sure both stages (the scraping process itself, and the doc build) emit complete dependency lists.

CC rust-lang#146220
Part of rust-lang#83784
GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this pull request Oct 30, 2025
@GuillaumeGomez
Rollup merge of rust-lang#148268 - notriddle:emit-scraped-examples, r…
a3633c3 
…=GuillaumeGomez

rustdoc: fix `--emit=dep-info` on scraped examples

Makes sure both stages (the scraping process itself, and the doc build) emit complete dependency lists.

CC rust-lang#146220
Part of rust-lang#83784
GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this pull request Nov 3, 2025
@GuillaumeGomez
Rollup merge of rust-lang#148268 - notriddle:emit-scraped-examples, r…
4f266bd 
…=GuillaumeGomez

rustdoc: fix `--emit=dep-info` on scraped examples

Makes sure both stages (the scraping process itself, and the doc build) emit complete dependency lists.

CC rust-lang#146220
Part of rust-lang#83784
rust-timer added a commit that referenced this pull request Nov 3, 2025
@rust-timer
Unrolled build for #148268
e61cede 
Rollup merge of #148268 - notriddle:emit-scraped-examples, r=GuillaumeGomez

rustdoc: fix `--emit=dep-info` on scraped examples

Makes sure both stages (the scraping process itself, and the doc build) emit complete dependency lists.

CC #146220
Part of #83784
github-actions bot pushed a commit to rust-lang/miri that referenced this pull request Nov 4, 2025
@GuillaumeGomez
Rollup merge of #148268 - notriddle:emit-scraped-examples, r=Guillaum…
2ed3bdb 
…eGomez

rustdoc: fix `--emit=dep-info` on scraped examples

Makes sure both stages (the scraping process itself, and the doc build) emit complete dependency lists.

CC rust-lang/rust#146220
Part of rust-lang/rust#83784
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@fmease fmease fmease left review comments

Assignees

@notriddle notriddle

@GuillaumeGomez GuillaumeGomez

Labels

needs-fcp This change is insta-stable, or significant enough to need a team FCP to proceed. S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@weihanglo @GuillaumeGomez @rustbot @fmease @notriddle