From c12a44fc3c76f6c74f1e8ba95c525965e0af9901 Mon Sep 17 00:00:00 2001
From: Michael Howell <michael@notriddle.com>
Date: Sun, 27 Oct 2024 11:22:21 -0700
Subject: [PATCH] rustdoc: Fix doctest `include` paths

CC https://github.com/rust-lang/rust/issues/132230
---
 src/SUMMARY.md                                |  1 +
 .../rustdoc-doctests-nested-include-str.md    | 64 +++++++++++++++++++
 2 files changed, 65 insertions(+)
 create mode 100644 src/rust-2024/rustdoc-doctests-nested-include-str.md

diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index 6cf543d..c5b8e4a 100644
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -57,3 +57,4 @@
   - [Unsafe attributes](rust-2024/unsafe-attributes.md)
   - [Rustdoc combined tests](rust-2024/rustdoc-doctests.md)
   - [Reserved syntax](rust-2024/reserved-syntax.md)
+  - [Rustdoc doctest nested `include_str!` change](rust-2024/rustdoc-doctests-nested-include-str.md)
diff --git a/src/rust-2024/rustdoc-doctests-nested-include-str.md b/src/rust-2024/rustdoc-doctests-nested-include-str.md
new file mode 100644
index 0000000..8f30153
--- /dev/null
+++ b/src/rust-2024/rustdoc-doctests-nested-include-str.md
@@ -0,0 +1,64 @@
+# 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 <https://github.com/rust-lang/rust/pull/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:
+
+```rust
+#![doc=include_str!("../README.md")]
+```
+
+And assume this `README.md` file:
+
+````markdown
+```
+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:
+
+```text
+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");
+  |                        ~~~~~~~~~~~~~~~~~~~
+```