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

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

View all comments

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 #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: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:

Concerns:

interaction-with-other-modes (feat(rustdoc): stabilize --emit flag #146220 (comment))
~~naming~~ resolved by feat(rustdoc): stabilize --emit flag #146220 (comment)
~~outdir-not-honored~~ resolved by feat(rustdoc): stabilize --emit flag #146220 (comment)
tiny-stab-report (feat(rustdoc): stabilize --emit flag #146220 (comment))

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.

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

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.

fmease · 2026-02-20T20:19:59Z

@rfcbot reviewed

Do we want a stabilization report?

I'd like to have a tiny stabilization report, just a few sentences esp. around the motivation would be great. For example, it's unclear to me right now whether Cargo is only interested in --emit=dep-info or if it also cares about the other two options toolchain-shared-resources & invocation-specific or rather the mechanism they enable, namely suppressing the emission of invocation-specific artifacts (via --emit=toolchain-shared-resources (sic!)) and shared resources (via --emit=invocation-specific (sic!)). That'd be useful to know imo.

@rfcbot concern tiny-stab-report

I've noticed that --emit=depinfo (i.e., default path) doesn't put the *.d file into the outdir but instead in the CWD. rustc does put in in the CWD by default but that's because the default outdir is the CWD. However, for rustdoc it's doc/. If you give rustc an --outdir=<DIR> it does put the *.d file into <DIR> while rustdoc completely ignores --outdir=<DIR> for depinfo.

Could we please honor the outdir?

@rfcbot concern outdir-not-honored

(minor bikeshedding) Re. the naming of toolchain-shared-resources and invocation-specific, it feels slightly off to me. I'll retract my concern immediately if everyone else is fine with these terms.

E.g., seeing the word toolchain in the context of the rustdoc binary seems a bit "weird". The (often rustup) toolchain is the set of rustc+rustdoc+docs+other components, they live at different level of abstraction? version-specific-shared-resources feels more natural, maybe? Although at this point, I'd just go with shared-resources. Isn't it obvious that these shared resources aren't stable across versions? If we hypothetically had a "stable rustdoc ABI", stable-shared-resources would do the trick, wouldn't it?

Re. --emit=invocation-specific, we're emitting an adjective here. I know, this is pure bikeshedding at this point and a noun like invocation-specific-data is hardly better?

@rfcbot concern naming

Lastly, what should we do if the user passes (stable) --test or (unstable) --output-format=doctest? Or if the user passes a *.md Markdown file to rustdoc (stable)? At the moment, --emit=dep-info doesn't emit any *.d file in these three cases because they take completely different execution paths in rustdoc. I'm leaning towards rejecting --emit=dep-info in these cases or is that too strict / artificially restricted? Or do we want to follow rustc's example: Under --test --emit=dep-info it doesn't generate any (test) binary, it only emits a *.d file.

@rfcbot concern interaction-with-other-modes

The following isn't an official concern and only tangentially related. I'm wondering whether --output-format=doctests (#134529) should actually be --emit=doctests. I'd also like to CC the proposed --print (#151618, print requests like rustc) for visibility, too. They're distinct but quite similar (I guess print requests are completely non-normal execution and emissions "happen on the side" during normal execution but they can also make execution halt early?).

fmease · 2026-02-20T20:23:57Z

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

(non-blocking, just some impl cleanups we should do at some point)

Under --emit=dep-info and --emit=invocation-specific rustdoc still generates an empty <OUTDIR>/static.files/ directory.

On unknown emission/output types rustdoc doesn't list all legal types in the error diagnostic unlike rustc.

notriddle · 2026-02-28T05:47:29Z

Re. the naming of toolchain-shared-resources and invocation-specific, it feels slightly off to me.

toolchain-shared-resources should probably be called static-files, because that's the name of the directory that it actually emits.

test-dingus % ls
lib.rs
test-dingus % rustdoc +nightly --emit=toolchain-shared-resources -Zunstable-options lib.rs
test-dingus % ls
doc	lib.rs
test-dingus % ls doc
static.files

Maybe the invocation-specific data should be called data-files? That one's harder to name, but we don't want to call it crate-files (because it might come from a standalone markdown file) and I think invocation-specific-files is needlessly complex for what it is.

rustdoc: make `--emit` and `--out-dir` mimic rustc The behavior in the test case matches rustc's: test-dingus % ls main.rs test-dingus % mkdir foobar test-dingus % rustc --emit=dep-info main.rs --out-dir=foobar test-dingus % ls foobar main.rs test-dingus % ls foobar main.d test-dingus % rustc --emit=dep-info=testfile.d main.rs --out-dir=foobar test-dingus % ls foobar main.rs testfile.d test-dingus % ls foobar main.d CC rust-lang#146220 (comment)

Rollup merge of #153003 - notriddle:emit-outdir, r=fmease rustdoc: make `--emit` and `--out-dir` mimic rustc The behavior in the test case matches rustc's: test-dingus % ls main.rs test-dingus % mkdir foobar test-dingus % rustc --emit=dep-info main.rs --out-dir=foobar test-dingus % ls foobar main.rs test-dingus % ls foobar main.d test-dingus % rustc --emit=dep-info=testfile.d main.rs --out-dir=foobar test-dingus % ls foobar main.rs testfile.d test-dingus % ls foobar main.d CC #146220 (comment)

fmease · 2026-03-04T13:04:28Z

@rfcbot resolve outdir-not-honored

Fixed in #153003. Thanks, notriddle!

rustdoc: rename `--emit` names These new names are pithier and match up with the rest of our terminology: - `--emit=html-static-files` matches the default name of the directory that it actually emits, which is `static.files` (the hyphen is used for emit because every other emit option uses hyphens, but the directory uses a dot because we don't want its name to conflict with a crate). - `--emit=html-non-static-files` matches the convention that emit is a noun, not an adjective, and it logically groups with other data formats. This commit changes the docs, but leaves in support for the old names, to break the cycle with cargo and docs.rs. This commit needs merged, then cargo and docs.rs will be updated to use the new names, then, finally, the old names will be removed. CC #146220 (comment)

rustdoc: rename `--emit` names These new names are pithier and match up with the rest of our terminology: - `--emit=html-static-files` matches the default name of the directory that it actually emits, which is `static.files` (the hyphen is used for emit because every other emit option uses hyphens, but the directory uses a dot because we don't want its name to conflict with a crate). - `--emit=html-non-static-files` matches the convention that emit is a noun, not an adjective, and it logically groups with other data formats. This commit changes the docs, but leaves in support for the old names, to break the cycle with cargo and docs.rs. This commit needs merged, then cargo and docs.rs will be updated to use the new names, then, finally, the old names will be removed. CC rust-lang#146220 (comment)

fmease · 2026-03-11T13:23:43Z

@rfcbot resolve naming

Fixed in #153460. Thanks, notriddle! If you disagree with the new names that were chosen please raise a new pFCP concern!

GuillaumeGomez · 2026-03-11T15:38:20Z

So just needs an update for the docs @weihanglo then the PR seems ready to go!

fmease · 2026-03-11T15:46:34Z

As well as a tiny stabilization report, please :D (FCP concern tiny-stab-report). Moreover, FCP concern interaction-with-other-modes hasn't been resolved yet.

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

27 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

This comment was marked as resolved.

Sign in to view

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

fmease reviewed Feb 20, 2026

View reviewed changes

notriddle mentioned this pull request Feb 23, 2026

rustdoc: make --emit and --out-dir mimic rustc #153003

Merged

fmease mentioned this pull request Feb 23, 2026

Stabilize rustdoc --merge --parts-out-dir, and --include-parts-dir options #152902

Open

notriddle mentioned this pull request Mar 5, 2026

rustdoc: rename --emit names #153460

Merged

Uh oh!

Conversation

weihanglo commented Sep 5, 2025 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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.

notriddle commented Jan 12, 2026

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

GuillaumeGomez commented Jan 12, 2026

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

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!

fmease commented Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fmease Feb 20, 2026 • edited 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 Feb 28, 2026

Uh oh!

fmease commented Mar 4, 2026

Uh oh!

fmease commented Mar 11, 2026

Uh oh!

GuillaumeGomez commented Mar 11, 2026

Uh oh!

fmease commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

weihanglo commented Sep 5, 2025 •

edited by rustbot

Loading

fmease commented Oct 25, 2025 •

edited

Loading

rust-rfcbot commented Jan 12, 2026 •

edited

Loading

fmease commented Feb 20, 2026 •

edited

Loading

fmease Feb 20, 2026 •

edited

Loading

fmease commented Mar 11, 2026 •

edited

Loading