rustdoc: make doctest span tweak a 2024 edition change

[notriddle]

Fixes #132203

This is a compatibility hack, because I think the new behavior is better. When an A include_str! B, and B include_str! C, the path to C should be resolved relative to B, not A. That's how include! itself works, so that's how include_str! with should work.

[rustbot]

r? @GuillaumeGomez

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

[GuillaumeGomez]

Nice, thanks!

@bors r+ rollup

[bors]

📌 Commit 1819b4f has been approved by GuillaumeGomez

It is now in the queue for this repository.

[compiler-errors]

Should this not be treated like any other edition 2024 change then, with a migration lint (or at least a best-effort attempt at detecting cases where users may be affected) and a section in the edition 2024 book? This seems a somewhat quick decision to gate this behind edition 2024, and presumably we shouldn't leave users in the dark when they're upgrading and their code suddenly breaks. cc @traviscross

[notriddle]

Should this not be treated like any other edition 2024 change then, with a migration lint (or at least a best-effort attempt at detecting cases where users may be affected) and a section in the edition 2024 book?

This should definitely be in the edition 2024 book.

As for the lint, I couldn't think of a good way to suggest a fix. There's no way to fix it before you migrate, and after you migrate, there already is a suggestion, as you can see in the crater reports.

Rustdoc doctest nested include_str! change

🚧 The 2024 Edition has not yet been released and hence this section is still "under construction".
More information may be found at #132210.

Summary

When a doctest is included with include_str!, if that doctest itself
also uses include! / include_str! / include_bytes!, the path is
resolved relative to the Markdown file, rather than the Rust
source file.

Details

Prior to the 2024 edition, adding documentation with
#[doc=include_str!("path/file.md")] didn't carry span information
into the doctests. As a result, if the Markdown file is in a different
directory than the source, any include!ed paths need to be relative
to the Rust file.

For example, consider a library crate with these files:

• Cargo.toml
• README.md
• src/
• • lib.rs
• examples/
• • data.bin

Let lib.rs contain this:

#![doc=include_str!("../README.md")]

And assume this README.md file:

```
let _ = include_bytes!("../examples/data.bin");
//                      ^^^ notice this
```

Prior to the 2024 edition, the path in README.md needed to be
relative to the lib.rs file. In 2024 and later, it is now relative
to README.md iself.

Migration

After migrating, you'll see the following error:

error: couldn't read `../examples/data.bin`: No such file or directory (os error 2)
 --> src/../README.md:2:24
  |
2 | let _ = include_bytes!("../examples/data.bin");
  |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  = note: this error originates in the macro `include_bytes` (in Nightly builds, run with -Z macro-backtrace for more info)
help: there is a file with the same name in a different directory
  |
2 | let _ = include_bytes!("examples/data.bin");
  |                        ~~~~~~~~~~~~~~~~~~~

[bors]

⌛ Testing commit 1819b4f with merge 466a6fa...

[traviscross]

@bors r-

(Edition-related. Comment to follow.)

[bors]

💔 Test failed - checks-actions

[traviscross]

While this seems a sensible change, it is very late to be adding an edition item. If this is to go into Rust 2024 at all, we need to follow some process to ensure this is ready for the edition before the change itself lands. Here's what needs to happen:

• File an edition tracking issue for the change. I've done this:
  • Tracking issue for Rust 2024: Fix doctest include paths #132230
• Complete the other required steps for an edition item. In particular:
  • Confirm whether or not there is some edition migration lint needed here, and if there is, implement it.
  • Write up a chapter for the edition guide and have it approved.
  • Confirm whether there are any changes needed to the Reference, and if so, put up that PR.
  • Confirm that this is a decision by the @rust-lang/rustdoc team to request a Rust 2024 edition item.
    • I don't see an FCP or other similar consensus decision, but maybe this was discussed elsewhere.
    • Alternatively, if this is an executive decision by the team lead acting on behalf of the team, that's fine too; it should just be stated explicitly.
  • Confirm with the edition team this can be accepted for the edition at the point these things are ready.
    • In particular, I want sign-off from @ehuss that this late change does not worry him too much with respect to how we test the edition with crater.
  • Then merge this PR landing the change in Rust 2024.

Hopefully this list doesn't seem too daunting. On net, I probably would like to see this happen. But there's some catch-up needed here if this is going to happen, and these items will need to all happen within a very short time -- days, not weeks.

Looking at the breakage, one alternative that the rustdoc team might want consider here is whether this bug might be fixed without making this an edition item at all. Perhaps there is a way to issue a FCW if it seems a crate is relying on the bug? Then PRs could be submitted to the affected crates. After some time, then perhaps the change could be landed (in all editions).

Please let us know what you want to do here, in particular if you do plan to quickly complete the steps needed to make this an edition item.

[traviscross]

The edition guide change is merged. There are no edition migration lints for this. @GuillaumeGomez has confirmed the rustdoc team wants this as an edition item.

On the edition side, we've discussed and can fit this into our testing with it merging now, so let's get it in.

I would r+ this, but it looks like from the logs above that some tests here still need to be fixed. When that's resolved, this is good to go, r=me,GuillaumeGomez.

[notriddle]

Okay, ignoring windows on the test that cares about path syntax.

[GuillaumeGomez]

Issue was approved so I'm planning on r+ing this PR by this evening. CI seems to have been cancelled so I'll wait for @notriddle to take another look here before doing anything.

[GuillaumeGomez]

CI is failing. Once fixed, please r=me. :)

[notriddle]

@bors r=GuillaumeGomez

[bors]

📌 Commit ac7de1a has been approved by GuillaumeGomez

It is now in the queue for this repository.