Skip to content

Commit 7411a9e

Browse files
jyn514jyn514
committed
rustdoc: link to stable/beta docs consistently in documentation
 ## 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
1 parent c4c2ab5 commit 7411a9e

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

41 files changed

+139
-120
lines changed

‎library/alloc/src/lib.rs

-1
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,6 @@
5959
#![allow(unused_attributes)]
6060
#![stable(feature = "alloc", since = "1.36.0")]
6161
#![doc(
62-
html_root_url = "https://doc.rust-lang.org/nightly/",
6362
html_playground_url = "https://play.rust-lang.org/",
6463
issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/",
6564
test(no_crate_inject, attr(allow(unused_variables), deny(warnings)))

‎library/core/src/lib.rs

-1
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,6 @@
5151
#![cfg(not(test))]
5252
#![stable(feature = "core", since = "1.6.0")]
5353
#![doc(
54-
html_root_url = "https://doc.rust-lang.org/nightly/",
5554
html_playground_url = "https://play.rust-lang.org/",
5655
issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/",
5756
test(no_crate_inject, attr(deny(warnings))),

‎library/panic_abort/src/lib.rs

+1-4
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,7 @@
55
66
#![no_std]
77
#![unstable(feature = "panic_abort", issue = "32837")]
8-
#![doc(
9-
html_root_url = "https://doc.rust-lang.org/nightly/",
10-
issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/"
11-
)]
8+
#![doc(issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/")]
129
#![panic_runtime]
1310
#![allow(unused_features)]
1411
#![feature(core_intrinsics)]

‎library/panic_unwind/src/lib.rs

+1-4
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,7 @@
1313
1414
#![no_std]
1515
#![unstable(feature = "panic_unwind", issue = "32837")]
16-
#![doc(
17-
html_root_url = "https://doc.rust-lang.org/nightly/",
18-
issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/"
19-
)]
16+
#![doc(issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/")]
2017
#![feature(core_intrinsics)]
2118
#![feature(lang_items)]
2219
#![feature(nll)]

‎library/proc_macro/src/lib.rs

-1
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,6 @@
1212
#![stable(feature = "proc_macro_lib", since = "1.15.0")]
1313
#![deny(missing_docs)]
1414
#![doc(
15-
html_root_url = "https://doc.rust-lang.org/nightly/",
1615
html_playground_url = "https://play.rust-lang.org/",
1716
issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/",
1817
test(no_crate_inject, attr(deny(warnings))),

‎library/std/src/lib.rs

-1
Original file line numberDiff line numberDiff line change
@@ -190,7 +190,6 @@
190190
#![cfg_attr(not(feature = "restricted-std"), stable(feature = "rust1", since = "1.0.0"))]
191191
#![cfg_attr(feature = "restricted-std", unstable(feature = "restricted_std", issue = "none"))]
192192
#![doc(
193-
html_root_url = "https://doc.rust-lang.org/nightly/",
194193
html_playground_url = "https://play.rust-lang.org/",
195194
issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/",
196195
test(no_crate_inject, attr(deny(warnings))),

‎library/term/src/lib.rs

+1-5
Original file line numberDiff line numberDiff line change
@@ -30,11 +30,7 @@
3030
//! [win]: https://docs.microsoft.com/en-us/windows/console/character-mode-applications
3131
//! [ti]: https://en.wikipedia.org/wiki/Terminfo
3232
33-
#![doc(
34-
html_root_url = "https://doc.rust-lang.org/nightly/",
35-
html_playground_url = "https://play.rust-lang.org/",
36-
test(attr(deny(warnings)))
37-
)]
33+
#![doc(html_playground_url = "https://play.rust-lang.org/", test(attr(deny(warnings))))]
3834
#![deny(missing_docs)]
3935
#![cfg_attr(windows, feature(libc))]
4036

‎library/test/src/lib.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919

2020
#![crate_name = "test"]
2121
#![unstable(feature = "test", issue = "50297")]
22-
#![doc(html_root_url = "https://doc.rust-lang.org/nightly/", test(attr(deny(warnings))))]
22+
#![doc(test(attr(deny(warnings))))]
2323
#![cfg_attr(unix, feature(libc))]
2424
#![feature(rustc_private)]
2525
#![feature(nll)]

‎src/bootstrap/builder.rs

+12
Original file line numberDiff line numberDiff line change
@@ -574,6 +574,18 @@ impl<'a> Builder<'a> {
574574
self.run_step_descriptions(&Builder::get_step_descriptions(Kind::Doc), paths);
575575
}
576576

577+
/// NOTE: keep this in sync with `rustdoc::clean::utils::doc_rust_lang_org_channel`, or tests will fail on beta/stable.
578+
pub fn doc_rust_lang_org_channel(&self) -> String {
579+
let channel = match &*self.config.channel {
580+
"stable" => &self.version,
581+
"beta" => "beta",
582+
"nightly" | "dev" => "nightly",
583+
// custom build of rustdoc maybe? link to the latest stable docs just in case
584+
_ => "stable",
585+
};
586+
"https://doc.rust-lang.org/".to_owned() + channel
587+
}
588+
577589
fn run_step_descriptions(&self, v: &[StepDescription], paths: &[PathBuf]) {
578590
StepDescription::run(v, self, paths);
579591
}

‎src/bootstrap/compile.rs

+5
Original file line numberDiff line numberDiff line change
@@ -326,6 +326,11 @@ pub fn std_cargo(builder: &Builder<'_>, target: TargetSelection, stage: u32, car
326326
if target.contains("riscv") {
327327
cargo.rustflag("-Cforce-unwind-tables=yes");
328328
}
329+
330+
let html_root =
331+
format!("-Zcrate-attr=doc(html_root_url=\"{}/\")", builder.doc_rust_lang_org_channel(),);
332+
cargo.rustflag(&html_root);
333+
cargo.rustdocflag(&html_root);
329334
}
330335

331336
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]

‎src/bootstrap/test.rs

+1
Original file line numberDiff line numberDiff line change
@@ -1486,6 +1486,7 @@ note: if you're sure you want to do this, please open an issue as to why. In the
14861486
}
14871487
}
14881488
cmd.env("RUSTC_BOOTSTRAP", "1");
1489+
cmd.env("DOC_RUST_LANG_ORG_CHANNEL", builder.doc_rust_lang_org_channel());
14891490
builder.add_rust_test_threads(&mut cmd);
14901491

14911492
if builder.config.sanitizers_enabled(target) {

‎src/bootstrap/tool.rs

+1
Original file line numberDiff line numberDiff line change
@@ -263,6 +263,7 @@ pub fn prepare_tool_cargo(
263263
cargo.env("CFG_RELEASE_CHANNEL", &builder.config.channel);
264264
cargo.env("CFG_VERSION", builder.rust_version());
265265
cargo.env("CFG_RELEASE_NUM", &builder.version);
266+
cargo.env("DOC_RUST_LANG_ORG_CHANNEL", builder.doc_rust_lang_org_channel());
266267

267268
let info = GitInfo::new(builder.config.ignore_git, &dir);
268269
if let Some(sha) = info.sha() {

‎src/etc/htmldocck.py

+4
Original file line numberDiff line numberDiff line change
@@ -135,6 +135,8 @@
135135
unichr = chr
136136

137137

138+
channel = os.environ["DOC_RUST_LANG_ORG_CHANNEL"]
139+
138140
class CustomHTMLParser(HTMLParser):
139141
"""simplified HTML parser.
140142
@@ -270,6 +272,7 @@ def flatten(node):
270272

271273

272274
def normalize_xpath(path):
275+
path = path.replace("{{channel}}", channel)
273276
if path.startswith('//'):
274277
return '.' + path # avoid warnings
275278
elif path.startswith('.//'):
@@ -334,6 +337,7 @@ def get_dir(self, path):
334337

335338

336339
def check_string(data, pat, regexp):
340+
pat = pat.replace("{{channel}}", channel)
337341
if not pat:
338342
return True # special case a presence testing
339343
elif regexp:

‎src/librustdoc/clean/types.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -499,7 +499,7 @@ impl Item {
499499
format!("{}/std/", s.trim_end_matches('/'))
500500
}
501501
Some(ExternalLocation::Unknown) | None => {
502-
"https://doc.rust-lang.org/nightly/std/".to_string()
502+
format!("{}/std/", crate::DOC_RUST_LANG_ORG_CHANNEL)
503503
}
504504
};
505505
// This is a primitive so the url is done "by hand".

‎src/librustdoc/clean/utils.rs

+5
Original file line numberDiff line numberDiff line change
@@ -543,3 +543,8 @@ crate fn has_doc_flag(attrs: ty::Attributes<'_>, flag: Symbol) -> bool {
543543
&& attr.meta_item_list().map_or(false, |l| rustc_attr::list_contains_name(&l, flag))
544544
})
545545
}
546+
547+
/// A link to `doc.rust-lang.org` that includes the channel name.
548+
///
549+
/// Set by `bootstrap::Builder::doc_rust_lang_org_channel` in order to keep tests passing on beta/stable.
550+
crate const DOC_RUST_LANG_ORG_CHANNEL: &'static str = env!("DOC_RUST_LANG_ORG_CHANNEL");

‎src/librustdoc/lib.rs

+2
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,8 @@ use rustc_session::config::{make_crate_type_option, ErrorOutputType, RustcOptGro
8181
use rustc_session::getopts;
8282
use rustc_session::{early_error, early_warn};
8383

84+
use crate::clean::utils::DOC_RUST_LANG_ORG_CHANNEL;
85+
8486
/// A macro to create a FxHashMap.
8587
///
8688
/// Example:

‎src/test/rustdoc-ui/check.rs

+1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
// check-pass
22
// compile-flags: -Z unstable-options --check
3+
// normalize-stderr-test: "nightly|beta|1\.[0-9][0-9]\.[0-9]" -> "$$CHANNEL"
34

45
#![warn(missing_docs)]
56
//~^ WARN

‎src/test/rustdoc-ui/check.stderr

+8-8
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
warning: missing documentation for the crate
2-
--> $DIR/check.rs:4:1
2+
--> $DIR/check.rs:5:1
33
|
44
LL | / #![warn(missing_docs)]
55
LL | |
@@ -10,30 +10,30 @@ LL | | pub fn foo() {}
1010
| |_______________^
1111
|
1212
note: the lint level is defined here
13-
--> $DIR/check.rs:4:9
13+
--> $DIR/check.rs:5:9
1414
|
1515
LL | #![warn(missing_docs)]
1616
| ^^^^^^^^^^^^
1717

1818
warning: missing documentation for a function
19-
--> $DIR/check.rs:9:1
19+
--> $DIR/check.rs:10:1
2020
|
2121
LL | pub fn foo() {}
2222
| ^^^^^^^^^^^^
2323

2424
warning: no documentation found for this crate's top-level module
2525
|
2626
note: the lint level is defined here
27-
--> $DIR/check.rs:7:9
27+
--> $DIR/check.rs:8:9
2828
|
2929
LL | #![warn(rustdoc::all)]
3030
| ^^^^^^^^^^^^
3131
= note: `#[warn(rustdoc::missing_crate_level_docs)]` implied by `#[warn(rustdoc::all)]`
3232
= help: The following guide may be of use:
33-
https://doc.rust-lang.org/nightly/rustdoc/how-to-write-documentation.html
33+
https://doc.rust-lang.org/$CHANNEL/rustdoc/how-to-write-documentation.html
3434

3535
warning: missing code example in this documentation
36-
--> $DIR/check.rs:4:1
36+
--> $DIR/check.rs:5:1
3737
|
3838
LL | / #![warn(missing_docs)]
3939
LL | |
@@ -44,14 +44,14 @@ LL | | pub fn foo() {}
4444
| |_______________^
4545
|
4646
note: the lint level is defined here
47-
--> $DIR/check.rs:7:9
47+
--> $DIR/check.rs:8:9
4848
|
4949
LL | #![warn(rustdoc::all)]
5050
| ^^^^^^^^^^^^
5151
= note: `#[warn(rustdoc::missing_doc_code_examples)]` implied by `#[warn(rustdoc::all)]`
5252

5353
warning: missing code example in this documentation
54-
--> $DIR/check.rs:9:1
54+
--> $DIR/check.rs:10:1
5555
|
5656
LL | pub fn foo() {}
5757
| ^^^^^^^^^^^^^^^

‎src/test/rustdoc-ui/intra-doc/email-address-localhost.rs

+1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
// normalize-stderr-test: "nightly|beta|1\.[0-9][0-9]\.[0-9]" -> "$$CHANNEL"
12
#![deny(warnings)]
23

34
//! Email me at <hello@localhost>.

‎src/test/rustdoc-ui/intra-doc/email-address-localhost.stderr

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,16 @@
11
error: unknown disambiguator `hello`
2-
--> $DIR/email-address-localhost.rs:3:18
2+
--> $DIR/email-address-localhost.rs:4:18
33
|
44
LL | //! Email me at <hello@localhost>.
55
| ^^^^^
66
|
77
note: the lint level is defined here
8-
--> $DIR/email-address-localhost.rs:1:9
8+
--> $DIR/email-address-localhost.rs:2:9
99
|
1010
LL | #![deny(warnings)]
1111
| ^^^^^^^^
1212
= note: `#[deny(rustdoc::broken_intra_doc_links)]` implied by `#[deny(warnings)]`
13-
= note: see https://doc.rust-lang.org/nightly/rustdoc/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators
13+
= note: see https://doc.rust-lang.org/$CHANNEL/rustdoc/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators
1414

1515
error: aborting due to previous error
1616

‎src/test/rustdoc-ui/intra-doc/unknown-disambiguator.rs

+1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
// normalize-stderr-test: "nightly|beta|1\.[0-9][0-9]\.[0-9]" -> "$$CHANNEL"
12
#![deny(warnings)]
23

34
//! Linking to [foo@banana] and [`bar@banana!()`].

‎src/test/rustdoc-ui/intra-doc/unknown-disambiguator.stderr

+13-13
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,56 @@
11
error: unknown disambiguator `foo`
2-
--> $DIR/unknown-disambiguator.rs:3:17
2+
--> $DIR/unknown-disambiguator.rs:4:17
33
|
44
LL | //! Linking to [foo@banana] and [`bar@banana!()`].
55
| ^^^
66
|
77
note: the lint level is defined here
8-
--> $DIR/unknown-disambiguator.rs:1:9
8+
--> $DIR/unknown-disambiguator.rs:2:9
99
|
1010
LL | #![deny(warnings)]
1111
| ^^^^^^^^
1212
= note: `#[deny(rustdoc::broken_intra_doc_links)]` implied by `#[deny(warnings)]`
13-
= note: see https://doc.rust-lang.org/nightly/rustdoc/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators
13+
= note: see https://doc.rust-lang.org/$CHANNEL/rustdoc/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators
1414

1515
error: unknown disambiguator `bar`
16-
--> $DIR/unknown-disambiguator.rs:3:35
16+
--> $DIR/unknown-disambiguator.rs:4:35
1717
|
1818
LL | //! Linking to [foo@banana] and [`bar@banana!()`].
1919
| ^^^
2020
|
21-
= note: see https://doc.rust-lang.org/nightly/rustdoc/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators
21+
= note: see https://doc.rust-lang.org/$CHANNEL/rustdoc/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators
2222

2323
error: unknown disambiguator `foo`
24-
--> $DIR/unknown-disambiguator.rs:9:34
24+
--> $DIR/unknown-disambiguator.rs:10:34
2525
|
2626
LL | //! And with weird backticks: [``foo@hello``] [foo`@`hello].
2727
| ^^^
2828
|
29-
= note: see https://doc.rust-lang.org/nightly/rustdoc/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators
29+
= note: see https://doc.rust-lang.org/$CHANNEL/rustdoc/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators
3030

3131
error: unknown disambiguator `foo`
32-
--> $DIR/unknown-disambiguator.rs:9:48
32+
--> $DIR/unknown-disambiguator.rs:10:48
3333
|
3434
LL | //! And with weird backticks: [``foo@hello``] [foo`@`hello].
3535
| ^^^
3636
|
37-
= note: see https://doc.rust-lang.org/nightly/rustdoc/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators
37+
= note: see https://doc.rust-lang.org/$CHANNEL/rustdoc/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators
3838

3939
error: unknown disambiguator ``
40-
--> $DIR/unknown-disambiguator.rs:6:31
40+
--> $DIR/unknown-disambiguator.rs:7:31
4141
|
4242
LL | //! And to [no disambiguator](@nectarine) and [another](@apricot!()).
4343
| ^
4444
|
45-
= note: see https://doc.rust-lang.org/nightly/rustdoc/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators
45+
= note: see https://doc.rust-lang.org/$CHANNEL/rustdoc/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators
4646

4747
error: unknown disambiguator ``
48-
--> $DIR/unknown-disambiguator.rs:6:57
48+
--> $DIR/unknown-disambiguator.rs:7:57
4949
|
5050
LL | //! And to [no disambiguator](@nectarine) and [another](@apricot!()).
5151
| ^
5252
|
53-
= note: see https://doc.rust-lang.org/nightly/rustdoc/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators
53+
= note: see https://doc.rust-lang.org/$CHANNEL/rustdoc/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators
5454

5555
error: aborting due to 6 previous errors
5656

‎src/test/rustdoc-ui/no-crate-level-doc-lint.rs

+1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
// error-pattern: no documentation found
2+
// normalize-stderr-test: "nightly|beta|1\.[0-9][0-9]\.[0-9]" -> "$$CHANNEL"
23
#![deny(rustdoc::missing_crate_level_docs)]
34
//^~ NOTE defined here
45

‎src/test/rustdoc-ui/no-crate-level-doc-lint.stderr

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
error: no documentation found for this crate's top-level module
22
|
33
note: the lint level is defined here
4-
--> $DIR/no-crate-level-doc-lint.rs:2:9
4+
--> $DIR/no-crate-level-doc-lint.rs:3:9
55
|
66
LL | #![deny(rustdoc::missing_crate_level_docs)]
77
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
88
= help: The following guide may be of use:
9-
https://doc.rust-lang.org/nightly/rustdoc/how-to-write-documentation.html
9+
https://doc.rust-lang.org/$CHANNEL/rustdoc/how-to-write-documentation.html
1010

1111
error: aborting due to previous error
1212

‎src/test/rustdoc/intra-doc/associated-items.rs

+3-3
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,9 @@
33
/// [`std::collections::BTreeMap::into_iter`]
44
/// [`String::from`] is ambiguous as to which `From` impl
55
/// [Vec::into_iter()] uses a disambiguator
6-
// @has 'associated_items/fn.foo.html' '//a[@href="https://doc.rust-lang.org/nightly/alloc/collections/btree/map/struct.BTreeMap.html#method.into_iter"]' 'std::collections::BTreeMap::into_iter'
7-
// @has 'associated_items/fn.foo.html' '//a[@href="https://doc.rust-lang.org/nightly/alloc/string/struct.String.html#method.from"]' 'String::from'
8-
// @has 'associated_items/fn.foo.html' '//a[@href="https://doc.rust-lang.org/nightly/alloc/vec/struct.Vec.html#method.into_iter"]' 'Vec::into_iter'
6+
// @has 'associated_items/fn.foo.html' '//a[@href="{{channel}}/alloc/collections/btree/map/struct.BTreeMap.html#method.into_iter"]' 'std::collections::BTreeMap::into_iter'
7+
// @has 'associated_items/fn.foo.html' '//a[@href="{{channel}}/alloc/string/struct.String.html#method.from"]' 'String::from'
8+
// @has 'associated_items/fn.foo.html' '//a[@href="{{channel}}/alloc/vec/struct.Vec.html#method.into_iter"]' 'Vec::into_iter'
99
pub fn foo() {}
1010

1111
/// Link to [MyStruct], [link from struct][MyStruct::method], [MyStruct::clone], [MyStruct::Input]

‎src/test/rustdoc/intra-doc/builtin-macros.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
// @has builtin_macros/index.html
2-
// @has - '//a/@href' 'https://doc.rust-lang.org/nightly/core/macro.cfg.html'
2+
// @has - '//a/@href' '{{channel}}/core/macro.cfg.html'
33
//! [cfg]

0 commit comments

Comments
 (0)