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

jonas-schievink · 2019-05-18T14:14:45Z

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

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

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 · 2019-05-18T14:14:56Z

r? @michaelwoerister

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

jonas-schievink · 2019-05-18T14:16:03Z

r? @GuillaumeGomez or @QuietMisdreavus

GuillaumeGomez · 2019-05-18T22:36:04Z

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 · 2019-06-03T13:00:11Z

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

cramertj · 2019-06-03T16:24:17Z

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 · 2019-06-03T16:55:43Z

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 · 2019-06-03T17:01:40Z

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 · 2019-06-10T16:20:01Z

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

src/libstd/os/raw/mod.rs

src/libsyntax/util/path.rs

petrochenkov · 2019-06-22T17:36:17Z

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 · 2019-06-22T20:21:27Z

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 · 2019-06-22T20:32:58Z

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.

rust-highfive · 2019-07-23T18:04:14Z

The job LinuxTools of your PR failed (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.

2019-07-23T15:58:45.3762271Z ##[command]git remote add origin https://github.com/rust-lang/rust
2019-07-23T15:58:45.3940204Z ##[command]git config gc.auto 0
2019-07-23T15:58:45.4005435Z ##[command]git config --get-all http.https://github.com/rust-lang/rust.extraheader
2019-07-23T15:58:45.4056259Z ##[command]git config --get-all http.proxy
2019-07-23T15:58:45.4178017Z ##[command]git -c http.extraheader="AUTHORIZATION: basic ***" fetch --force --tags --prune --progress --no-recurse-submodules --depth=2 origin +refs/heads/*:refs/remotes/origin/* +refs/pull/60938/merge:refs/remotes/pull/60938/merge
---
2019-07-23T15:59:23.8198819Z do so (now or later) by using -b with the checkout command again. Example:
2019-07-23T15:59:23.8198865Z 
2019-07-23T15:59:23.8215711Z   git checkout -b <new-branch-name>
2019-07-23T15:59:23.8215943Z 
2019-07-23T15:59:23.8216052Z HEAD is now at e748b6bf8 Merge 218ab4cd7fdf145a0870c582a23ad5fd85cd80e5 into 3ebca72a11869f946b31f900faffb75c2bb2473a
2019-07-23T15:59:23.8347903Z ##[section]Finishing: Checkout
2019-07-23T15:59:23.8355754Z ##[section]Starting: Decide whether to run this job
2019-07-23T15:59:23.8359211Z Task         : Bash
2019-07-23T15:59:23.8359249Z Description  : Run a Bash script on macOS, Linux, or Windows
2019-07-23T15:59:23.8359305Z Version      : 3.151.3
2019-07-23T15:59:23.8359344Z Author       : Microsoft Corporation
2019-07-23T15:59:23.8359344Z Author       : Microsoft Corporation
2019-07-23T15:59:23.8359386Z Help         : https://docs.microsoft.com/azure/devops/pipelines/tasks/utility/bash
2019-07-23T15:59:23.8359446Z ==============================================================================
2019-07-23T15:59:23.9568438Z Generating script.
2019-07-23T15:59:23.9597680Z ========================== Starting Command Output ===========================
2019-07-23T15:59:23.9616202Z [command]/bin/bash --noprofile --norc /home/vsts/work/_temp/ca66f7ee-aa33-4513-bae6-071dfc489b4c.sh
2019-07-23T15:59:24.2662572Z Executing the job since submodules are updated
2019-07-23T15:59:24.2745517Z ##[section]Finishing: Decide whether to run this job
2019-07-23T15:59:24.2755527Z ==============================================================================
2019-07-23T15:59:24.2755571Z Task         : Bash
2019-07-23T15:59:24.2755644Z Description  : Run a Bash script on macOS, Linux, or Windows
2019-07-23T15:59:24.2755679Z Version      : 3.151.3
---
2019-07-23T18:03:40.6240604Z Verifying status of embedded-book...
2019-07-23T18:03:40.6252710Z Verifying status of rustc-guide...
2019-07-23T18:03:40.6401253Z Cloning into 'rust-toolstate'...
2019-07-23T18:03:41.3424352Z The state of "rustc-guide" has changed from "test-pass" to ""
2019-07-23T18:03:41.3656464Z [master 4bda9b2] (linux CI update)
2019-07-23T18:03:42.1237555Z remote: Invalid username or password.
2019-07-23T18:03:42.1237555Z remote: Invalid username or password.
2019-07-23T18:03:42.1239021Z fatal: Authentication failed for 'https://github.com/rust-lang-nursery/rust-toolstate.git/'
2019-07-23T18:03:45.4603565Z  * branch            master     -> FETCH_HEAD
2019-07-23T18:03:45.4776213Z HEAD is now at 1c20fe8 (windows CI update)
2019-07-23T18:03:45.4888251Z The state of "rustc-guide" has changed from "test-pass" to ""
2019-07-23T18:03:45.5069710Z [master 0a8c1ae] (linux CI update)
2019-07-23T18:03:45.5069710Z [master 0a8c1ae] (linux CI update)
2019-07-23T18:03:45.5069954Z  1 file changed, 1 insertion(+)
2019-07-23T18:03:45.8449153Z fatal: could not read Username for 'https://github.com': No such device or address
2019-07-23T18:03:47.1867686Z  * branch            master     -> FETCH_HEAD
2019-07-23T18:03:47.2021479Z HEAD is now at 1c20fe8 (windows CI update)
2019-07-23T18:03:47.2132706Z The state of "rustc-guide" has changed from "test-pass" to ""
2019-07-23T18:03:47.2312601Z [master 3156f8c] (linux CI update)
2019-07-23T18:03:47.2312601Z [master 3156f8c] (linux CI update)
2019-07-23T18:03:47.2313021Z  1 file changed, 1 insertion(+)
2019-07-23T18:03:47.5543270Z fatal: could not read Username for 'https://github.com': No such device or address
2019-07-23T18:03:48.9067342Z  * branch            master     -> FETCH_HEAD
2019-07-23T18:03:48.9223899Z HEAD is now at 1c20fe8 (windows CI update)
2019-07-23T18:03:48.9340868Z The state of "rustc-guide" has changed from "test-pass" to ""
2019-07-23T18:03:48.9510181Z [master 1348238] (linux CI update)
2019-07-23T18:03:48.9510181Z [master 1348238] (linux CI update)
2019-07-23T18:03:48.9510530Z  1 file changed, 1 insertion(+)
2019-07-23T18:03:49.2657359Z fatal: could not read Username for 'https://github.com': No such device or address
2019-07-23T18:03:50.6056035Z  * branch            master     -> FETCH_HEAD
2019-07-23T18:03:50.6211911Z HEAD is now at 1c20fe8 (windows CI update)
2019-07-23T18:03:50.6328061Z The state of "rustc-guide" has changed from "test-pass" to ""
2019-07-23T18:03:50.6509274Z [master aeea6b5] (linux CI update)
2019-07-23T18:03:50.6509274Z [master aeea6b5] (linux CI update)
2019-07-23T18:03:50.6510048Z  1 file changed, 1 insertion(+)
2019-07-23T18:03:50.9790517Z fatal: could not read Username for 'https://github.com': No such device or address
2019-07-23T18:03:53.3125414Z  * branch            master     -> FETCH_HEAD
2019-07-23T18:03:53.3271937Z HEAD is now at 1c20fe8 (windows CI update)
2019-07-23T18:03:53.3271937Z HEAD is now at 1c20fe8 (windows CI update)
2019-07-23T18:03:54.2829337Z ##[error]Bash exited with code '1'.
2019-07-23T18:03:54.2864874Z ##[section]Starting: Checkout
2019-07-23T18:03:54.2866915Z ==============================================================================
2019-07-23T18:03:54.2866992Z Task         : Get sources
2019-07-23T18:03:54.2867040Z Description  : Get sources from a repository. Supports Git, TfsVC, and SVN repositories.

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 · 2019-07-23T22:35:44Z

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

@bors r=petrochenkov

bors · 2019-07-23T22:35:45Z

📌 Commit 218ab4c has been approved by petrochenkov

…r=petrochenkov rustdoc: make #[doc(include)] relative to the containing file This matches the behavior of other in-source paths like `#[path]` and the `include_X!` macros. Fixes rust-lang#58373 (comment) Also addresses rust-lang#44732 (comment) cc rust-lang#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.

@ghost

Rollup of 10 pull requests Successful merges: - rust-lang#60938 (rustdoc: make #[doc(include)] relative to the containing file) - rust-lang#61890 (Fix some sanity checks) - rust-lang#62261 (Take substs into account in `conservative_is_privately_uninhabited`) - rust-lang#62528 (Add joining slices of slices with a slice separator, not just a single item) - rust-lang#62735 (Turn `#[global_allocator]` into a regular attribute macro) - rust-lang#62801 (Remove support for -Zlower-128bit-ops) - rust-lang#62808 (Revert "Disable stack probing for gnux32.") - rust-lang#62819 (Display name of crate requiring rustc_private in error messages.) - rust-lang#62904 (Disable d32 on armv6 hf targets) - rust-lang#62907 (Initialize the MSP430 AsmParser) Failed merges: r? @ghost

…r=petrochenkov rustdoc: make #[doc(include)] relative to the containing file This matches the behavior of other in-source paths like `#[path]` and the `include_X!` macros. Fixes rust-lang#58373 (comment) Also addresses rust-lang#44732 (comment) cc rust-lang#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.

@ghost

Rollup of 13 pull requests Successful merges: - rust-lang#60938 (rustdoc: make #[doc(include)] relative to the containing file) - rust-lang#61890 (Fix some sanity checks) - rust-lang#62084 (allow clippy::unreadable_literal in unicode tables) - rust-lang#62261 (Take substs into account in `conservative_is_privately_uninhabited`) - rust-lang#62528 (Add joining slices of slices with a slice separator, not just a single item) - rust-lang#62735 (Turn `#[global_allocator]` into a regular attribute macro) - rust-lang#62801 (Remove support for -Zlower-128bit-ops) - rust-lang#62808 (Revert "Disable stack probing for gnux32.") - rust-lang#62822 (Improve some pointer-related documentation) - rust-lang#62904 (Disable d32 on armv6 hf targets) - rust-lang#62907 (Initialize the MSP430 AsmParser) - rust-lang#62921 (Add method disambiguation help for trait implementation) - rust-lang#62942 (Use match ergonomics in Condvar documentation) Failed merges: r? @ghost

…r=petrochenkov rustdoc: make #[doc(include)] relative to the containing file This matches the behavior of other in-source paths like `#[path]` and the `include_X!` macros. Fixes rust-lang#58373 (comment) Also addresses rust-lang#44732 (comment) cc rust-lang#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.

@ghost

Rollup of 15 pull requests Successful merges: - #60066 (Stabilize the type_name intrinsic in core::any) - #60938 (rustdoc: make #[doc(include)] relative to the containing file) - #61884 (Stablize Euclidean Modulo (feature euclidean_division)) - #61890 (Fix some sanity checks) - #62528 (Add joining slices of slices with a slice separator, not just a single item) - #62707 (Add tests for overlapping explicitly dropped locals in generators) - #62735 (Turn `#[global_allocator]` into a regular attribute macro) - #62822 (Improve some pointer-related documentation) - #62887 (Make the parser TokenStream more resilient after mismatched delimiter recovery) - #62921 (Add method disambiguation help for trait implementation) - #62930 (Add test for #51559) - #62942 (Use match ergonomics in Condvar documentation) - #62977 (Fix inconsistent highlight blocks.) - #62978 (Remove `cfg(bootstrap)` code for array implementations) - #62981 (Add note suggesting to borrow a String argument to find) Failed merges: - #62964 (clarify and unify some type test names) r? @ghost

Since rust-lang/rust#60938 the path root changed and these new paths are required to compile on nightly.

Since rust-lang/rust#60938 the path root changed and these new paths are required to compile on nightly. Closes #268.

jonas-schievink added the T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. label May 18, 2019

rust-highfive assigned michaelwoerister May 18, 2019

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label May 18, 2019

rust-highfive assigned GuillaumeGomez and unassigned michaelwoerister May 18, 2019

This comment has been minimized.

Sign in to view

Dylan-DPC-zz added S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jun 3, 2019

QuietMisdreavus added the T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. label Jun 10, 2019

petrochenkov self-assigned this Jun 17, 2019

petrochenkov added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jun 22, 2019

petrochenkov reviewed Jun 22, 2019

View reviewed changes

src/libstd/os/raw/mod.rs Outdated Show resolved Hide resolved

petrochenkov reviewed Jun 22, 2019

View reviewed changes

src/libsyntax/util/path.rs Outdated Show resolved Hide resolved

petrochenkov removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. labels Jun 22, 2019

jonas-schievink added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). labels Jun 22, 2019

jonas-schievink mentioned this pull request Jun 22, 2019

Adjust #[doc(include)] paths for rustdoc change rust-lang/stdarch#769

Merged

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Jul 23, 2019

Centril mentioned this pull request Jul 24, 2019

Rollup of 10 pull requests #62936

Closed

Centril mentioned this pull request Jul 24, 2019

Rollup of 13 pull requests #62960

Closed

Centril mentioned this pull request Jul 25, 2019

Rollup of 9 pull requests #62966

Closed

Centril mentioned this pull request Jul 25, 2019

Rollup of 15 pull requests #62990

Merged

bors merged commit 218ab4c into rust-lang:master Jul 26, 2019

jplatte mentioned this pull request Jul 31, 2019

Centralize panic macro documentation #61511

Closed

hdevalence mentioned this pull request Jul 31, 2019

Update nightly pin and doc include paths. dalek-cryptography/bulletproofs#291

Merged

hdevalence added a commit to dalek-cryptography/curve25519-dalek that referenced this pull request Jul 31, 2019

Update doc(include) paths.

0d1f7bc

Since rust-lang/rust#60938 the path root changed and these new paths are required to compile on nightly.

hdevalence added a commit to dalek-cryptography/curve25519-dalek that referenced this pull request Jul 31, 2019

Update doc(include) paths.

5c18bfb

Since rust-lang/rust#60938 the path root changed and these new paths are required to compile on nightly. Closes #268.

This was referenced Jul 31, 2019

Update doc(include) paths. dalek-cryptography/curve25519-dalek#269

Merged

Fix link to AVX2 docs dalek-cryptography/curve25519-dalek#275

Merged

Warn about path change for #[doc(include)] #63335

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

jonas-schievink commented May 18, 2019

rust-highfive commented May 18, 2019

jonas-schievink commented May 18, 2019

This comment has been minimized.

GuillaumeGomez commented May 18, 2019

This comment has been minimized.

Dylan-DPC-zz commented Jun 3, 2019

cramertj commented Jun 3, 2019

jonas-schievink commented Jun 3, 2019

cramertj commented Jun 3, 2019

QuietMisdreavus commented Jun 10, 2019

petrochenkov commented Jun 22, 2019

rust-highfive commented Jun 22, 2019

jonas-schievink commented Jun 22, 2019

rust-highfive commented Jul 23, 2019

jonas-schievink commented Jul 23, 2019

bors commented Jul 23, 2019

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

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

Conversation

jonas-schievink commented May 18, 2019

rust-highfive commented May 18, 2019

jonas-schievink commented May 18, 2019

This comment has been minimized.

GuillaumeGomez commented May 18, 2019

This comment has been minimized.

Dylan-DPC-zz commented Jun 3, 2019

cramertj commented Jun 3, 2019

jonas-schievink commented Jun 3, 2019

cramertj commented Jun 3, 2019

QuietMisdreavus commented Jun 10, 2019

petrochenkov commented Jun 22, 2019

rust-highfive commented Jun 22, 2019

jonas-schievink commented Jun 22, 2019

rust-highfive commented Jul 23, 2019

jonas-schievink commented Jul 23, 2019

bors commented Jul 23, 2019