Rustdoc nested include! change - The Rust Edition Guide

## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# Rustdoc nested `include!` change

## Summary

When a doctest is included with `include_str!`, if that doctest itself also uses `include!`, `include_str!`, or `include_bytes!`, the path is resolved relative to the Markdown file, rather than to 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 any doctests in that file. As a result, if the Markdown file was in a different directory than the source, any paths included had to be specified relative to the source file.

For example, consider a library crate with these files:

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

Let’s say that `lib.rs` contains 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` itself, so we would update `README.md` to:

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

## Migration

There is no automatic migration to convert the paths in affected doctests. If one of your doctests is affected, you’ll see an error like this after migrating to the new edition when building your tests:

    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");
      |                        ~~~~~~~~~~~~~~~~~~~

To migrate your doctests to Rust 2024, update any affected paths to be relative to the file containing the doctests.