Fix, simplify, and document doc meta finalize mode by notriddle · Pull Request #159473 · rust-lang/rust

notriddle · 2026-07-17T22:35:07Z

Get rid of the mode where you can finalize the CCI and generate more docs at the same time. It isn't used in Cargo, and probably won't be used elsewhere?

Fixes a bug where the crate index, settings page, and help page aren’t generated at finalize time.

Update documentation.

Move CCI tests to run-make, so that we can test the finalize step’s CLI.

rustbot · 2026-07-17T22:35:12Z

r? @folkertdev

rustbot has assigned @folkertdev.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

Owners of files modified in this PR: compiler
compiler expanded to 74 candidates
Random selection from 17 candidates

notriddle · 2026-07-17T22:36:25Z

r? @camelid

rustbot · 2026-07-17T22:36:29Z

camelid is currently at their maximum review capacity.
They may take a while to respond.

Since we're getting rid of the ability to do finalize and document at the same time, we can't actually do this in the rustdoc-html test build system and need to do it this way instead.

Co-authored-by: Noah Lev <37223377+camelid@users.noreply.github.com>

rustbot · 2026-07-26T02:19:44Z

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.

camelid

Looks good overall, but I'd like to avoid the dummy crate and TyCtxt, and some of the tests seem to be translated wrong from the original files.

View changes since this review

camelid · 2026-07-27T17:56:50Z

+            let config = core::create_config(
+                Input::Str {
+                    name: rustc_span::FileName::Custom(String::new()),
+                    input: String::new(),
+                },
+                options,
+                &render_options,
+            );
            return wrap_return(
                dcx,
-                rustc_span::create_session_globals_then(options.edition, &[], None, || {
-                    run_merge_finalize(render_options)
+                interface::run_compiler(config, |compiler| {
+                    run_merge_finalize(render_options, compiler)


Ditto here, but getting rid of the fake Input::Str is harder, and this seems less bad than making a fake crate and TyCtxt. So fine to just leave it.

camelid · 2026-07-29T18:31:07Z

We're also missing the root-level help.html and settings.html files in the finalize step.

notriddle · 2026-07-30T03:15:18Z

Good catch! settings.html and help.html are moved, so they get generated at finalize now.

camelid

Thanks! r=me with comments addressed. Or feel free to just merge and then fix in a later PR since this is already a big improvement.

Also, could you rename the title and edit the PR description since the scope has changed and grown a bit?

View changes since this review

camelid · 2026-07-31T21:07:45Z

Have we specified the behavior of rustdoc when two different invocations use the same --write-doc-meta-dir folder?

notriddle · 2026-08-01T04:42:50Z

Have we specified the behavior of rustdoc when two different invocations use the same --write-doc-meta-dir folder?

Good point. I've added a mention of this to the unstable book.

camelid · 2026-08-02T02:16:15Z

Good point. I've added a mention of this to the unstable book.

I asked mostly because I wonder if we should forbid/not support this use case. Otherwise we need to support reading multiple crates' metadata from a single flag's metadata directory. It might force us into adding extra structure to our metadata directories to make sure that different crates' entries don't clash.

camelid · 2026-08-05T17:24:27Z

Thanks! @bors r+

rust-bors · 2026-08-05T17:24:30Z

📌 Commit 227eea7 has been approved by camelid

It is now in the queue for this repository.

…uwer Rollup of 12 pull requests Successful merges: - #159014 ([rustdoc] Do not take `doc(cfg())` into account when filtering doctests) - #159029 (rustc_llvm: Emit module summaries when using -Clto=fat) - #160574 (Update rustc-perf submodule) - #154585 (treat no_mangle_generic_items as hard error instead of lint warning) - #159473 (Fix, simplify, and document doc meta finalize mode) - #157489 (Add CoerceShared field-wise reborrow WF checks) - #160532 (Add Enzyme bugfix to support rust+llvm23) - #160545 (Reorder the methods in `#[rustc_must_implement_one_of]`) - #160558 (Revert "codegen_ssa: no dbginfo for scalable vec local w/ `-O0`") - #160566 (Re-enable bool indexing assembly test for LLVM 23) - #160569 (Remove `OnDuplicate::Custom`) - #160576 ([rustdoc] Create output file after we checked that the standalone markdown file is valid)

Rollup merge of #159473 - notriddle:rename-parts-to-dep-meta, r=camelid Fix, simplify, and document doc meta finalize mode Follow up #159415 (comment) Get rid of the mode where you can finalize the CCI and generate more docs at the same time. It isn't used in Cargo, and probably won't be used elsewhere? Fixes a bug where the crate index, settings page, and help page aren’t generated at finalize time. Update documentation. Move CCI tests to run-make, so that we can test the finalize step’s CLI.

…uwer Rollup of 12 pull requests Successful merges: - rust-lang/rust#159014 ([rustdoc] Do not take `doc(cfg())` into account when filtering doctests) - rust-lang/rust#159029 (rustc_llvm: Emit module summaries when using -Clto=fat) - rust-lang/rust#160574 (Update rustc-perf submodule) - rust-lang/rust#154585 (treat no_mangle_generic_items as hard error instead of lint warning) - rust-lang/rust#159473 (Fix, simplify, and document doc meta finalize mode) - rust-lang/rust#157489 (Add CoerceShared field-wise reborrow WF checks) - rust-lang/rust#160532 (Add Enzyme bugfix to support rust+llvm23) - rust-lang/rust#160545 (Reorder the methods in `#[rustc_must_implement_one_of]`) - rust-lang/rust#160558 (Revert "codegen_ssa: no dbginfo for scalable vec local w/ `-O0`") - rust-lang/rust#160566 (Re-enable bool indexing assembly test for LLVM 23) - rust-lang/rust#160569 (Remove `OnDuplicate::Custom`) - rust-lang/rust#160576 ([rustdoc] Create output file after we checked that the standalone markdown file is valid)

…red-target crates out rust-lang/rust#159473 (merged 2026-08-06) made passing both --write-doc-meta-dir and --read-doc-meta-dir to one rustdoc invocation a hard error -- exactly what this script's old aggregator step did. Our pinned nightly (2026-07-21) predates that change, so the script still worked, but would break the moment the toolchain pin moves past it. Rewritten as a genuine finalize-only step: a bare `rustdoc` invocation (no cargo, no crate source -- finalize mode doesn't take any anymore) reading every meta directory and writing the merged glue files directly. This also drops the old aggregator's `AGGREGATOR_CRATE`/rebuild-with-a-second-CARGO_TARGET_DIR complexity entirely, since finalize mode has no cargo fingerprint to fight with. Along the way, hit a second issue: on our pinned nightly, finalize mode silently doesn't write help.html/settings.html at all (the exact bug rust-lang/rust#159473 itself describes fixing, but our pin predates the fix). Since those two files are static UI chrome with no crate-specific content, they're now generated via an ordinary, non-merge-mode rustdoc call on a throwaway empty crate instead -- sidesteps the bug on old nightlies and is unaffected by whatever else changes about finalize mode's behavior in the future. Added a comment documenting what we've learned about this feature's stability (tracking issue, stabilization PR status, the two upstream changes that motivated this rewrite, and why cargo's separate -Z rustdoc-mergeable-info automation doesn't apply here), so the next person hitting a break on a toolchain bump has pointers. Also split CRATE_TARGETS into CRATE_TARGETS (one crate, one real target, unambiguous) and SHARED_CRATE_TARGETS (crates whose dependent boards actually build for more than one real target, where picking one is a deliberate, somewhat arbitrary call: riscv/riscv-csr serve both riscv32 and riscv64 boards, cortexm/cortexv7m serve both thumbv7em and thumbv8m.main boards) -- folded back into CRATE_TARGETS before use, so nothing downstream changes. Verified this split is exhaustive: checked every CRATE_TARGETS crate's actual board dependents' .cargo/config.toml target lines; only these four crates resolve to more than one distinct target. Verified: a full `NOWARNINGS=true` doc build on the pinned nightly still produces 169/169 crates, 34/34 static files, correct help.html/settings.html, and a clean cortexm/cortexm33/riscv/x86 MPU trait-impl merge with no duplicates. Additionally verified the finalize step and empty-crate chrome generation against a nightly after rust-lang/rust#159473 (installing riscv32imac-unknown-none-elf/ thumbv7em-none-eabi targets for it) -- same clean merge, confirming this works on both sides of the toolchain change that motivated the rewrite. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018kKWYpBqL9jafD7rtvt9qH

…nto unified docs build_all_docs.sh cross-compiles arch/* and select chips/* crates against their real target triples instead of the host, and merges the results into one unified doc tree using rustdoc's cross-crate-info merging mechanism (RFC 3662, "Mergeable rustdoc cross-crate info": --write-doc-meta-dir/--read-doc-meta-dir, gated behind -Z unstable-options). This lets those crates drop the `doc` half of their cfg gates, since their real (not mocked) implementation gets documented directly. This relies entirely on rustdoc's own merge logic -- the script never parses or rewrites rustdoc's own output format -- but the flags it's built on are still actively changing shape, not close to stabilizing: - rust-lang/rust#130676 is the tracking issue. - rust-lang/rust#152902, the stabilization PR, is S-blocked/needs-fcp. Its FCP was cancelled 2026-07-17 pending interface changes, and T-rustdoc has floated replacing the whole mechanism with info embedded in .rmeta files instead. As of 2026-08-07 the team wants to "dogfood this feature a bit" before reconsidering stabilization. - rust-lang/rust#159415 (merged 2026-07-17) renamed the RFC's original --parts-out-dir / --include-parts-dir / --merge=none|shared|finalize flags to today's --write-doc-meta-dir / --read-doc-meta-dir. - rust-lang/rust#159473 (merged 2026-08-06) removed the mode this script's finalize step would otherwise need (passing both --write-doc-meta-dir and --read-doc-meta-dir to one invocation) -- that combination is a hard error on recent nightlies, and finalize mode (--read-doc-meta-dir) takes no crate source at all. That's why the finalize step below runs bare `rustdoc`, not `cargo rustdoc -p ...`. - Cargo has a separate, less mature automation layer for this (-Z rustdoc-mergeable-info, tracked by rust-lang/cargo#16306) -- not an option here, since it's explicitly same-target-only and this script's whole point is merging docs built for different targets. Expect to revisit this script on future toolchain bumps. CRATE_TARGETS is a plain indexed array of "crate:target-triple" entries (rather than an associative array via `declare -A`) deliberately: macOS ships bash 3.2, which predates associative arrays entirely. Crates whose dependent boards/chips actually build for more than one real target -- where picking one is a deliberate, somewhat arbitrary call rather than a fact about the crate -- are called out separately in SHARED_CRATE_TARGETS and folded into CRATE_TARGETS before use. Verified: run the script locally; diff the set of crates listed in the merged `crates.js` against the previous single-pass build's output -- every crate still appears. Spot-checked that `trait.impl/kernel/platform/mpu/trait.MPU.js` shows implementors from more than one arch crate, confirming cross-crate merging works. Verified against both the pinned nightly and a nightly after rust-lang/rust#159473, installing missing target components as needed, confirming the finalize step works on both sides of that upstream change. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018kKWYpBqL9jafD7rtvt9qH

rustbot assigned folkertdev Jul 17, 2026

rustbot assigned camelid and unassigned folkertdev Jul 17, 2026

notriddle mentioned this pull request Jul 17, 2026

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

Open

camelid reviewed Jul 23, 2026

View reviewed changes

camelid added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jul 23, 2026

fmease reviewed Jul 25, 2026

View reviewed changes

Comment thread tests/run-make/rustdoc/merge-cross-crate-info/kitchen-sink-separate-dirs/indigo.rs

notriddle and others added 9 commits July 25, 2026 19:06

rustdoc: fix --enable-index-page with finalize

91131bb

rustdoc: move CCI tests to run-make

a36c898

Since we're getting rid of the ability to do finalize and document at the same time, we can't actually do this in the rustdoc-html test build system and need to do it this way instead.

rustdoc: write rmake scripts to test CCI

6887d4d

Document the changed doc meta features

32f1625

Update src/doc/rustdoc/src/unstable-features.md

18d6ebf

Co-authored-by: Noah Lev <37223377+camelid@users.noreply.github.com>

Update src/doc/rustdoc/src/unstable-features.md

ac3994e

Co-authored-by: Noah Lev <37223377+camelid@users.noreply.github.com>

rustdoc: clean up unused @ build diectives

c352016

rustdoc: no --read-doc-meta-dir and --write-doc-meta-dir at once

e03942b

rustdoc: move CCI run-make tests into the directory

d0fec14

notriddle force-pushed the rename-parts-to-dep-meta branch from 9e2125b to d0fec14 Compare July 26, 2026 02:19

camelid 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 Jul 27, 2026

camelid requested changes Jul 27, 2026

View reviewed changes

This comment has been minimized.

Sign in to view

rustdoc: generate settings and help at finalize

5f940df

notriddle force-pushed the rename-parts-to-dep-meta branch from 23fae6c to 5f940df Compare July 30, 2026 05:57

camelid approved these changes Jul 31, 2026

View reviewed changes

notriddle added 3 commits July 31, 2026 21:21

rustdoc: use fs::write on no-crate-specific HTML

b777427

rustdoc: remove unused root path code

c83df33

rustdoc: document you can use one shared meta dir

227eea7

camelid mentioned this pull request Aug 3, 2026

rustdoc: Tracking issue for mergeable cross-crate info #130676

Open

6 tasks

notriddle changed the title ~~Simplify doc meta mode~~ Fix doc meta finalize mode Aug 5, 2026

notriddle changed the title ~~Fix doc meta finalize mode~~ Fix, simplify, and document doc meta finalize mode Aug 5, 2026

rust-bors Bot added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Aug 5, 2026

JonathanBrouwer mentioned this pull request Aug 5, 2026

Rollup of 12 pull requests #160586

Merged

camelid mentioned this pull request Aug 5, 2026

bootstrap: Enable rustdoc mergeable CCI for std and internal docs #160098

Open

rust-bors Bot merged commit 408fecd into rust-lang:main Aug 6, 2026
13 checks passed

rustbot added this to the 1.99.0 milestone Aug 6, 2026

notriddle deleted the rename-parts-to-dep-meta branch August 6, 2026 02:29

Uh oh!

Uh oh!

Conversation

notriddle commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented Jul 17, 2026

Uh oh!

notriddle commented Jul 17, 2026

Uh oh!

rustbot commented Jul 17, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rustbot commented Jul 26, 2026

Uh oh!

camelid 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!

Uh oh!

camelid Jul 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

camelid commented Jul 29, 2026

Uh oh!

notriddle commented Jul 30, 2026

Uh oh!

This comment has been minimized.

camelid 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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

camelid commented Jul 31, 2026

Uh oh!

notriddle commented Aug 1, 2026

Uh oh!

camelid commented Aug 2, 2026

Uh oh!

camelid commented Aug 5, 2026

Uh oh!

rust-bors Bot commented Aug 5, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

notriddle commented Jul 17, 2026 •

edited

Loading

camelid left a comment •

edited by rustbot

Loading

camelid left a comment •

edited by rustbot

Loading