Move to doc links inside the prelude

[poliorcetics]

Helps with #75080.

@rustbot modify labels: T-doc, A-intra-doc-links, T-rustdoc

[rust-highfive]

r? @LukasKalbertodt

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

[jyn514]

@bors r+ rollup

Good catch with the module@vec :)

[bors]

📌 Commit 8ff768e21d93bc1cf78e89a4925a4f28ec314cfa has been approved by jyn514

[poliorcetics]

It's not my achievement, rustdoc caught the ambiguity by itself, which is amazing !

[poliorcetics]

It fails on the module@crate::vec on CI but doesn't on my machine. @jyn514 any idea on how to fix this ?

[jyn514]

@bors r-

[jyn514]

@poliorcetics try rebasing over master? I might have broken something in #75079 or #75318.

[poliorcetics]

Rebasing did nothing (my branch is an hour old at most at this point) and rebuilding from scratch still worked when doing ./x.py doc library/std --stage 1.

[jyn514]

Not sure then, I'll have to debug it. I wish we had #75305 :(

[poliorcetics]

Exact error:

error: `[crate::vec]` cannot be resolved, ignoring it.
  --> library/std/src/prelude/mod.rs:78:19
   |
78 | //! [`std::vec`]: module@crate::vec
   |                   ^^^^^^^^^^^^^^^^^ cannot be resolved, ignoring
   |
   = note: `-D intra-doc-link-resolution-failure` implied by `-D warnings`
   = help: to escape `[` and `]` characters, just add '\' before them like `\[` or `\]`

error: aborting due to previous error

I see a [crate::vec] at the top which makes little sense to me, it is expected ?

[LukasKalbertodt]

Looks like this PR is already in good hands :)

r? @jyn514

[jyn514]

CI is documenting using stage 0, which doesn't have the latest fixes to intra-doc links. Not sure what this exact failure is from, but this will break anyway when we start linking to associated items (#74489).

@Mark-Simulacrum do you know why mingw-check uses doc --stage 0 library/std? Is it just for efficiency? I think we should either add -A broken_intra_doc_links or skip the check altogether if --stage 1 is too expensive to run.

[jyn514]

This would probably work if it went through a full bors build, but then the whole compiler will have broken mingw-check builds on every PR, so I don't want to do that unilaterally.

[jyn514]

This was added in 1f7c896. @ecstatic-morse, what was the rationale for using --stage 0 instead of --stage 1?

[poliorcetics]

The PR that made the change was #71649 if that helps.

[Mark-Simulacrum]

--stage 0 is intentionally checked (other stages are checked already on other builders) because we want to ensure that docs are buildable and viewable locally; this means that docs contributors don't need to build anything locally.

In the future I'd like for that to not be necessary, instead that we provide an easy way for a "recent master build" or perhaps nightly to work, but as of now that's not really feasible.

[poliorcetics]

I moved the std::vec link back to a path, to make it compile and allow this to be merged.

@jyn514 do you think making a note in the tracking issue is possible (both for the affected files as they are found and a more generic one to warn people) ?

[jyn514]

we want to ensure that docs are buildable and viewable locally

Hmm ... if the intra-doc link breaks it will still be viewable, there will just be some broken links. What do you think about having cfg_attr(bootstrap, allow(broken_intra_doc_links))? That way x.py doc still works but we still ensure we have working links on nightly.

Merging this PR since it has good changes :) but I think it's worth continuing the discussion.

@bors r+ rollup

[bors]

📌 Commit 3ff06a9 has been approved by jyn514

[Mark-Simulacrum]

I would prefer to avoid that - we only have a few weeks to go - but if it is truly necessary, then it should go into bootstrap/builder.rs along with other warnings. I can review such a PR.

[jyn514]

Well it's not certain that #74489 will get merged before the beta cutoff ... but other issues seems rare enough that we can delay the discussion until then, I agree if it's only 1 or 2 weeks it's not worth special casing and we can just do it after the new release.