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

weihanglo · 2025-09-05T00:00:58Z

TODO: stabilization report?

r? rustdoc

weihanglo · 2025-09-05T00:03:31Z

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 · 2025-09-11T19:48:52Z

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

src/doc/rustdoc/src/command-line-arguments.md

GuillaumeGomez · 2025-10-13T20:51:02Z

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.

weihanglo · 2025-10-13T23:22:09Z

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

fmease · 2025-10-25T18:00:15Z

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

weihanglo · 2025-10-25T18:33:33Z

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.

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 · 2025-10-27T17:24:00Z

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.

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

…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

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

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

View changes since this review

…=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

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

…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

notriddle · 2026-01-12T20:51:43Z

I haven’t found any more problems with this feature (that don’t involve its interaction with other unstable features).

I think it can be stabilized in its current form.

GuillaumeGomez · 2026-01-12T20:53:24Z

@rfcbot fcp merge

rust-rfcbot · 2026-01-12T20:53:26Z

Error encounted:
Provided team `` is invalid

GuillaumeGomez · 2026-01-12T20:54:14Z

@rfcbot fcp merge rustdoc

rust-rfcbot · 2026-01-12T20:54:17Z

Team member @GuillaumeGomez has proposed to merge this. The next step is review by the rest of the tagged team members:

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

yotamofek · 2026-01-13T13:25:34Z

src/doc/rustdoc/src/command-line-arguments.md

+This flag controls the types of output by rustdoc. It accepts a comma-separated
+list of values, and may be specified multiple times. The valid emit kinds are:
+
+- `toolchain-shared-resources` --- Generates shared static files that their


Suggested change

- `toolchain-shared-resources` --- Generates shared static files that their

- `toolchain-shared-resources` --- Generates shared static files whose

yotamofek · 2026-01-13T13:26:39Z

src/doc/rustdoc/src/command-line-arguments.md

+  change if the toolchain version or their contents change, so it is safe to
+  cache them wit the `Cache-Control: immutable` directive.


Suggested change

change if the toolchain version or their contents change, so it is safe to

cache them wit the `Cache-Control: immutable` directive.

change if the toolchain version or their contents change, or with the `Cache-Control: immutable` directive.

Updated. Thanks!

yotamofek · 2026-01-13T13:28:01Z

src/doc/rustdoc/src/command-line-arguments.md

+This flag controls the types of output by rustdoc. It accepts a comma-separated
+list of values, and may be specified multiple times. The valid emit kinds are:
+
+- `toolchain-shared-resources` --- Generates shared static files that their


Not sure whether these triple-dashes are considered standard :)

It's a mdbook stuff. Not sure about rustdoc but Cargo book uses that everywhere

https://rust-lang.github.io/mdBook/format/markdown.html#smart-punctuation

rustbot · 2026-01-13T16:09:57Z

This PR was rebased onto a different main 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.

rustbot assigned GuillaumeGomez Sep 5, 2025

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 marked this pull request as ready for review September 24, 2025 19:21

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

fmease reviewed Oct 13, 2025

View reviewed changes

src/doc/rustdoc/src/command-line-arguments.md Outdated Show resolved Hide resolved

notriddle self-assigned this Oct 13, 2025

fmease mentioned this pull request Oct 13, 2025

rustdoc's --emit=dep-info=- doesn't output to STDOUT unlike rustc's #147649

Closed

weihanglo force-pushed the rustdoc-emit branch from e1a5014 to cc82db2 Compare October 25, 2025 15:56

This comment has been minimized.

Sign in to view

weihanglo force-pushed the rustdoc-emit branch from cc82db2 to bfb63c3 Compare October 25, 2025 16:04

weihanglo mentioned this pull request Oct 25, 2025

chore(triagebot): enable range-diff and review-changes-since rust-lang/cargo#16152

Merged

fmease mentioned this pull request Oct 25, 2025

rustdoc: follow-up work for --emit=toolchain-shared-resources #83784

Open

3 tasks

ojeda mentioned this pull request Oct 26, 2025

rustdoc wanted features & bugfixes Rust-for-Linux/linux#350

Open

26 tasks

notriddle mentioned this pull request Oct 27, 2025

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

Merged

weihanglo force-pushed the rustdoc-emit branch from bfb63c3 to b7f8908 Compare October 27, 2025 18:49

This comment has been minimized.

Sign in to view

weihanglo commented Oct 29, 2025

View reviewed changes

notriddle mentioned this pull request Oct 29, 2025

rustdoc: fix --emit=dep-info on scraped examples #148268

Merged

rust-rfcbot added proposed-final-comment-period Proposed to merge/close by relevant subteam, see T-<team> label. Will enter FCP once signed off. disposition-merge This issue / PR is in PFCP or FCP with a disposition to merge it. labels Jan 12, 2026

yotamofek reviewed Jan 13, 2026

View reviewed changes

feat(rustdoc): stabilize --emit flag

d5d59c7

weihanglo force-pushed the rustdoc-emit branch from b7f8908 to d5d59c7 Compare January 13, 2026 16:09

	- `toolchain-shared-resources` --- Generates shared static files that their
	- `toolchain-shared-resources` --- Generates shared static files whose

		change if the toolchain version or their contents change, so it is safe to
		cache them wit the `Cache-Control: immutable` directive.

Uh oh!

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

Are you sure you want to change the base?

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

Uh oh!

Conversation

weihanglo commented Sep 5, 2025

Uh oh!

weihanglo commented Sep 5, 2025

Uh oh!

weihanglo commented Sep 11, 2025

Uh oh!

Uh oh!

GuillaumeGomez commented Oct 13, 2025

Uh oh!

weihanglo commented Oct 13, 2025

Uh oh!

This comment has been minimized.

fmease commented Oct 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

weihanglo commented Oct 25, 2025

Uh oh!

notriddle commented Oct 27, 2025

Uh oh!

This comment has been minimized.

weihanglo left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

notriddle commented Jan 12, 2026

Uh oh!

GuillaumeGomez commented Jan 12, 2026

Uh oh!

rust-rfcbot commented Jan 12, 2026

Uh oh!

GuillaumeGomez commented Jan 12, 2026

Uh oh!

rust-rfcbot commented Jan 12, 2026 • edited by yotamofek Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yotamofek Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

yotamofek Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

weihanglo Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

yotamofek Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

weihanglo Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

rustbot commented Jan 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

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

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

fmease commented Oct 25, 2025 •

edited

Loading

weihanglo left a comment •

edited by rustbot

Loading

rust-rfcbot commented Jan 12, 2026 •

edited by yotamofek

Loading