Skip to content

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

New issue

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

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

Already on GitHub? # to your account

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
Contributor

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 force-pushed the beta-primitive branch from 7d7b439 to 19d4b04 Compare May 5, 2021 04:01
@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
Collaborator

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).
# for free to join this conversation on GitHub. Already have an account? # 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