feat(rustdoc): stabilize --emit flag

[weihanglo]

View all comments

---> FCP <---

Stabilization Report: rustdoc --emit

Feature: rustdoc --emit
Tracking issue: #83784
Stabilization PR: #146220

What we are stabilizing

This stabilizes the rustdoc --emit flag, which controls what types of output rustdoc produces. The flag accepts a comma-separated list of the following emit types:

• html-static-files --- Shared static files with content-hashed filenames for safe caching.
• html-non-static-files --- Per-crate documentation files with deterministic filenames.
• dep-info[=<path>] --- A Makefile-compatible .d file listing all source files loaded during documentation generation. Same as rustc's dep-info files.

When --emit is not specified, the default behavior is --emit=html-static-files,html-non-static-files (i.e., full HTML documentation output, no dep-info).

What we are not stabilizing

• Interaction between other unstable options, such as -Zrustdoc-mergeable-info and --output-format=doctest
• Available options and the default options when --emit not specified.
• Extension of per-type emit paths for options currently missing that.

Motivation

Cargo

The primary consumer is Cargo, which needs --emit=dep-info=<path> to precisely track the input dependencies of a rustdoc invocation (see the -Zrustdoc-depinfo unstable Cargo feature). Without dep-info, Cargo cannot detect changes to files pulled in via #[path = "..."] or similar mechanisms and leads to stale documentation in incremental builds.

Cargo also uses the selective emission mechanism (html-static-files / html-non-static-files) when the unstable -Zrustdoc-mergeable-info feature is active. It skips writing shared static files and search index during per-crate doc generation and defer them to a final merge phase.

Under stable usage, Cargo passes all three emit types together.

docs.rs

docs.rs is the other major consumer. It uses selective emission to avoid redundantly copying toolchain-wide static files for every crate, which has historically been a source of breakage. See the tracking #83784 and the about page for more https://docs.rs/about/download.

Tests

• tests/run-make/emit-shared-files --- Verifies selective emission of static vs non-static files.
• tests/run-make/rustdoc-dep-info --- Verifies dep-info generation, including explicit path and --out-dir interaction.
• tests/run-make/rustdoc-scrape-examples-dep-info --- Verifies dep-info works with scrape-examples.
• tests/run-make/rustdoc-default-output/ --- Verifies --help output shows [html-static-files,html-non-static-files,dep-info]

[weihanglo]

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]

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

[GuillaumeGomez]

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]

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]

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

[weihanglo]

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.

[notriddle]

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.

[fmease]

@rfcbot resolve interaction-with-other-modes

As already mentioned, we now emit an error if --emit and --test are specified at the same time (PR #153895). Moreover, --emit=depinfo now works for Markdown input files (PR #154352).

--emit=html-static-files, --emit=dep-info still emits a HTML artifact for Markdown input files despite --emit not containing html-non-static-files if the flag is specified like that. That's tracked in #155298 (ideally it would be fixed before the stabilization but it's not super pressing).

We still don't honor --emit under --output-format doctests -Zunstable-options but it's okay to postpone that.

@rfcbot resolve tiny-stab-report

Thanks, weihanglo, for adding a stabilization report!

[notriddle]

#155374 adds a few more tests for this functionality

[rust-rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[rustbot]

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.

[rust-rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

[GuillaumeGomez]

Thanks everyone!

@bors r+ rollup

[rust-bors]

📌 Commit cef0e99 has been approved by GuillaumeGomez

It is now in the queue for this repository.