rustdoc: make #[doc(include)] relative to the containing file

[jonas-schievink]

This matches the behavior of other in-source paths like #[path] and the include_X! macros.

Fixes #58373 (comment)
Also addresses #44732 (comment)

cc #44732

This is still missing a stdsimd change (https://github.com/jonas-schievink/stdsimd/commit/42ed30e0b5fb5e2d11765b5d1e1f36234af85984), so CI will currently fail. I'll land that change once I get initial feedback for this PR.

[rust-highfive]

r? @michaelwoerister

(rust_highfive has picked a reviewer for you, use r? to override)

[jonas-schievink]

r? @GuillaumeGomez or @QuietMisdreavus

[GuillaumeGomez]

Changes look good to me. However two things: first, since it's changing libsyntax, we'll need someone from the @rust-lang/compiler team to take a look. Second, I recall us having a document explaining rustdoc features. Please update/add this behaviour into it.

[Dylan-DPC-zz]

ping from triage, waiting from feedback from @rust-lang/compiler

[cramertj]

This matches the behavior of other in-source paths like #[path] and the include_X! macros.

FWIW, #[path] is not relative to the including file-- the relationship is much more complicated than that unfortunately :(. See #55560 for more info.

[jonas-schievink]

Oh, that's unfortunate. Perhaps something that could be fixed in the next edition.

Correct me if I'm wrong, but it would still hold for the usual use case of #[path] to include another file from inside a non-inline module, right?

[cramertj]

Correct me if I'm wrong, but it would still hold for the usual use case of #[path] to include another file from inside a non-inline module, right?

If you're inside a file named mod.rs/lib.rs/main.rs, yes, but otherwise no.

[QuietMisdreavus]

+1 for changing the implementation of doc(include). It's confused enough people that we should just defer to the behavior of include!() and friends. (The behavior of #[path] is odd, but i would consider that secondary to the intent of this PR. I haven't seen #[path] brought up in path-root confusion, just include_str!() - after all, #[doc(include="filename")] was supposed to be sugar for #[doc=include_str!("filename")].) I know i've been an obstacle to changing this behavior in the past, but after seeing it break stdsimd, i'd rather save the headache for everyone else.

[petrochenkov]

The change looks entirely reasonable to me and using a common function is a good way to ensure the behavior won't diverge.
So, r=me with the nits addressed if rustdoc team is happy with the change.

[rust-highfive]

The job x86_64-gnu-llvm-6.0 of your PR failed on Travis (raw log). Through arcane magic we have determined that the following fragments from the build log may contain information about the problem.

Click to expand the log.

travis_time:end:236d0ff0:start=1561233267195445824,finish=1561233269315700261,duration=2120254437
$ git checkout -qf FETCH_HEAD
travis_fold:end:git.checkout

Encrypted environment variables have been removed for security reasons.
See https://docs.travis-ci.com/user/pull-requests/#pull-requests-and-security-restrictions
$ export SCCACHE_BUCKET=rust-lang-ci-sccache2
$ export SCCACHE_REGION=us-west-1
$ export GCP_CACHE_BUCKET=rust-lang-ci-cache
$ export AWS_ACCESS_KEY_ID=AKIA46X5W6CZEJZ6XT55
---
[00:26:22]    Compiling cc v1.0.35
[00:26:22]    Compiling core v0.0.0 (/checkout/src/libcore)
[00:26:22]    Compiling libc v0.2.54
[00:26:22]    Compiling unwind v0.0.0 (/checkout/src/libunwind)
[00:26:22] error: couldn't read src/libcore/../stdsimd/crates/core_arch/src/../stdsimd/crates/core_arch/src/core_arch_docs.md: No such file or directory (os error 2)
[00:26:22]    |
[00:26:22]    |
[00:26:22] 13 |     doc(include = "../stdsimd/crates/core_arch/src/core_arch_docs.md")
[00:26:22]    |                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ couldn't read file
[00:26:22]    Compiling build_helper v0.1.0 (/checkout/src/build_helper)
[00:26:23]    Compiling autocfg v0.1.4
[00:26:25]    Compiling backtrace v0.3.29
[00:26:28]    Compiling compiler_builtins v0.1.16
---
travis_time:end:013a209c:start=1561234884298851755,finish=1561234884303616034,duration=4764279
travis_fold:end:after_failure.3
travis_fold:start:after_failure.4
travis_time:start:090dde4a
$ ln -s . checkout && for CORE in obj/cores/core.*; do EXE=$(echo $CORE | sed 's|obj/cores/core\.[0-9]*\.!checkout!\(.*\)|\1|;y|!|/|'); if [ -f "$EXE" ]; then printf travis_fold":start:crashlog\n\033[31;1m%s\033[0m\n" "$CORE"; gdb --batch -q -c "$CORE" "$EXE" -iex 'set auto-load off' -iex 'dir src/' -iex 'set sysroot .' -ex bt -ex q; echo travis_fold":"end:crashlog; fi; done || true
travis_fold:end:after_failure.4
travis_fold:start:after_failure.5
travis_time:start:1391eac5
travis_time:start:1391eac5
$ cat ./obj/build/x86_64-unknown-linux-gnu/native/asan/build/lib/asan/clang_rt.asan-dynamic-i386.vers || true
cat: ./obj/build/x86_64-unknown-linux-gnu/native/asan/build/lib/asan/clang_rt.asan-dynamic-i386.vers: No such file or directory
travis_fold:end:after_failure.5
travis_fold:start:after_failure.6
travis_time:start:06dbc17e
$ dmesg | grep -i kill

I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact @TimNN. (Feature Requests)

[jonas-schievink]

Okay, if @rust-lang/rustdoc is happy with this now, this only needs rust-lang/stdarch#769 to land and a submodule update. There seems to be some trouble with updating stdsimd though (#61540), so marking as blocked.

[jonas-schievink]

Failure is due to #62811, so this should be able to land regardless.

@bors r=petrochenkov

[bors]

📌 Commit 218ab4c has been approved by petrochenkov