rustdoc: Add unstable --merge-doctests=yes/no/auto flag

[jyn514]

This is useful for changing the default for whether doctests are merged or not. Currently, that default is solely controlled by edition = 2024, which adds a high switching cost to get doctest merging. This flag allows opting in even on earlier editions.

Unlike the edition = 2024 default, --merge-doctests=yes gives a hard error if merging fails instead of falling back to running standalone tests. The user has explicitly said they want merging, so we shouldn't silently do something else.

--merge-doctests=auto is equivalent to the current 2024 edition behavior, but available on earlier editions.

Helps with #141240. @epage said in that issue he would like a per-doctest opt-in, and that seems useful to me in addition to this flag, but I think it's a separate use case from changing the default.

[rustbot]

r? @notriddle

rustbot has assigned @notriddle.
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

[jyn514]

this error kinda sucks, but this is an unstable feature anyway, and with -C save-temps people will actually be able to inspect the merged code, which should make this easier to debug.

oh, maybe this should recommend -C save-temps as a note?

[jyn514]

hm this broke the reference’s doctest somehow

      failures:
      
      ---- items/constant-items.md - Constant_items (line 71) stdout ----
      Test compiled successfully, but it's marked `compile_fail`.
      ---- items/constant-items.md - Constant_items (line 97) stdout ----
      Test compiled successfully, but it's marked `compile_fail`.
      
      failures:
          items/constant-items.md - Constant_items (line 71)
          items/constant-items.md - Constant_items (line 97)

[jyn514]

i'm completely unable to reproduce this :/ i see ci has this output which i don't see locally:

[2025-12-03T00:03:32Z WARN  mdbook::preprocess::cmd] The command wasn't found, is the "spec" preprocessor installed?
[2025-12-03T00:03:32Z WARN  mdbook::preprocess::cmd] 	Command: cargo run --release --manifest-path mdbook-spec/Cargo.toml

[jyn514]

i ran rustdoc +stage2 --test src/items/constant-items.md manually and it doesn't even show the same line numbers as CI :/ what on earth

[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.

[epage]

Am I reading this correctly that this overrides standalone_crate?

From the PR description (emphasis mine)

This is useful for changing the default for whether doctests are merged or not.

For me, default implies that this is what we do in the absence of other information. standalone_crate is an obvious one for being respected. compile_fail is another. test_harness I'm unsure about.

Now, for any of the detection based on the code (global allocator, crate attrs, macros, $crate, etc, I see that being part of the autodetection.

[epage]

In case it is relevant, https://github.com/epage/rust/commits/merged_crate is where I left off on my work on the attribute

[jyn514]

excellent catch, omg. fixed this and added a test.

[jyn514]

something really weird is going on with compiletest; locally it applies the normalize-stdout directive, but in CI it ignores it and replaces $DIR. the two don't match, hence the failure, but I don't understand why $DIR would possibly work in CI but not locally.

for now I'm just going to change the normalization to match compiletest's normalization.

[jyn514]

oh, i wonder if this is about absolute vs relative paths :/

[jyn514]

i think the proper fix here is that rustdoc should use to_embeddable_absolute_path when -Z ui-testing is set. but i've already spent a bunch of time on this so i'm just going to open an issue and hopefully someone gets to it later.

[epage]

Don't know why I'm getting a chuckle at that variable name :)