Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

rustdoc: Don't link to stable/beta docs for primitives #84941

Closed
wants to merge 1 commit into from

Conversation

jyn514
Copy link
Member

@jyn514 jyn514 commented May 5, 2021

This has two issues:

  1. The test suite is not set up for links that differ based on the
    channel. This is not a giant deal; it's fixed by
    jyn514@2a21264.
  2. It's inconsistent with non-primitive types, because libstd uses
    html_root_url = "rust-lang.org/nightly". Fixing this is non-trivial,
    and the usefulness has also been called into question; see
    https://rust-lang.zulipchat.com/#narrow/stream/122651-general/topic/Rustdoc.20unconditionally.20links.20to.20nightly.20libstd.20docs.

To avoid being inconsistent, this reverts linking to beta for now.

cc @pietroalbini, this should fix the test failure in #84909 (comment) if you backport it.

@rust-highfive
Copy link
Collaborator

r? @ollie27

(rust-highfive has picked a reviewer for you, use r? to override)

@rust-highfive rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label May 5, 2021
@jyn514
Copy link
Member Author

jyn514 commented May 5, 2021

hmm, r? @Mark-Simulacrum maybe

@jyn514 jyn514 changed the title Don't link to stable/beta docs for primitives rustdoc: Don't link to stable/beta docs for primitives May 5, 2021
@rust-log-analyzer

This comment has been minimized.

This has two issues:

1. The test suite is not set up for links that differ based on the
channel. This is not a giant deal; it's fixed by
2a21264.
2. It's inconsistent with non-primitive types, because libstd uses
`html_root_url = "rust-lang.org/nightly"`. Fixing this is non-trivial,
and the usefulness has also been called into question; see
https://rust-lang.zulipchat.com/#narrow/stream/122651-general/topic/Rustdoc.20unconditionally.20links.20to.20nightly.20libstd.20docs.

To avoid being inconsistent, this reverts linking to beta for now.
@jyn514 jyn514 added the T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. label May 5, 2021
@pietroalbini
Copy link
Member

@bors r+

@rustbot modify-labels: beta-accepted

@bors
Copy link
Contributor

bors commented May 5, 2021

📌 Commit 19d4b04 has been approved by pietroalbini

@bors 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-review Status: Awaiting review from the assignee but also interested parties. labels May 5, 2021
@pietroalbini
Copy link
Member

@bors r-

The change also breaks Rustdoc UI tests, see #84909 (comment):

30    |         ^^^^^^^^^^^^
31    = note: `#[warn(rustdoc::missing_crate_level_docs)]` implied by `#[warn(rustdoc::all)]`
32    = help: The following guide may be of use:
-            https://doc.rust-lang.org/nightly/rustdoc/how-to-write-documentation.html
+            https://doc.rust-lang.org/beta/rustdoc/how-to-write-documentation.html
35 warning: missing code example in this documentation
36   --> $DIR/check.rs:4:1

I'll open a PR to revert the whole 3478f83 commit.

@bors bors 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-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels May 5, 2021
@pietroalbini
Copy link
Member

Superseded by #84950.

@jyn514 jyn514 deleted the beta-primitive branch May 5, 2021 11:07
JohnTitor added a commit to JohnTitor/rust that referenced this pull request Jun 4, 2021
rustdoc: link to stable/beta docs consistently in documentation

This is an alternative to rust-lang#84941 which fixes the problem consistently by linking to stable/beta for *all* items, not just for primitives.

 ## User-facing changes

- Intra-doc links to primitives that currently go to rust-lang.org/nightly/std/primitive.x.html will start going to channel that rustdoc was built with. Nightly will continue going to /nightly; Beta will link to /beta; stable compilers will link to /1.52.1 (or whatever version they were built as).
- Cross-crate links from std to core currently go to /nightly unconditionally. They will start going to /1.52.0 on stable channels (but remain the same on nightly channels).
- Intra-crate links from std to std (or core to core) currently go to the same URL they are hosted at; they will continue to do so. Notably, this is different from everything else because it can preserve the distinction between /stable and /1.52.0 by using relative links.

Note that "links" includes both intra-doc links and rustdoc's own
automatically generated hyperlinks.

 ## Implementation changes

- Update the testsuite to allow linking to /beta and /1.52.1 in docs
- Use an html_root_url for the standard library that's dependent on the channel

  This avoids linking to nightly docs on stable.

- Update rustdoc to use channel-dependent links for primitives from an
  unknown crate

- Set DOC_RUST_LANG_ORG_CHANNEL from bootstrap to ensure it's in sync
- Include doc.rust-lang.org in the channel

cc Mark-Simulacrum - I know [you were dubious about this in the past](https://rust-lang.zulipchat.com/#narrow/stream/122651-general/topic/Rustdoc.20unconditionally.20links.20to.20nightly.20libstd.20docs/near/231223124), but I'm not quite sure why? I see this as "just a bugfix", I don't know why rustdoc should unconditionally link to nightly.
cc dtolnay who commented in rust-lang#30693:

>  I would welcome a PR to solve this permanently if anyone has ideas for how. I don't believe we need an RFC.

Fixes rust-lang#30693 (note that issue is marked as feature-accepted, although I don't see where it was discussed).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants