From 962c0a4ee59e3c1a2413e785694c9433ffd0a9e1 Mon Sep 17 00:00:00 2001 From: Jacob Hoffman-Andrews Date: Fri, 3 Dec 2021 17:09:04 -0800 Subject: [PATCH] Make source links look cleaner Change from syntaxy-looking [src] to the plain word "source". --- library/std/src/lib.rs | 4 +- src/librustdoc/html/render/context.rs | 2 +- src/librustdoc/html/render/mod.rs | 14 ++++-- src/librustdoc/html/render/print_item.rs | 6 +-- src/librustdoc/html/static/css/rustdoc.css | 32 +++++++----- src/librustdoc/html/static/css/themes/ayu.css | 2 +- .../html/static/css/themes/dark.css | 2 +- .../html/static/css/themes/light.css | 6 +-- src/librustdoc/html/templates/print_item.html | 50 ++++++++++--------- src/test/rustdoc-gui/anchors.goml | 6 ++- src/test/rustdoc-gui/headings.goml | 8 +-- src/test/rustdoc-gui/toggle-docs.goml | 3 ++ src/test/rustdoc/ensure-src-link.rs | 2 +- src/test/rustdoc/external-macro-src.rs | 4 +- src/test/rustdoc/issue-16265-1.rs | 6 ++- src/test/rustdoc/issue-16265-2.rs | 4 +- src/test/rustdoc/issue-26606.rs | 2 +- src/test/rustdoc/src-links-auto-impls.rs | 6 +-- src/test/rustdoc/thread-local-src.rs | 4 +- src/test/rustdoc/trait-src-link.rs | 12 ++--- 20 files changed, 96 insertions(+), 79 deletions(-) diff --git a/library/std/src/lib.rs b/library/std/src/lib.rs index d5f9d20c426e2..4ba4e2a528e60 100644 --- a/library/std/src/lib.rs +++ b/library/std/src/lib.rs @@ -35,8 +35,8 @@ //! development you may want to press the `[-]` button near the top of the //! page to collapse it into a more skimmable view. //! -//! While you are looking at that `[-]` button also notice the `[src]` -//! button. Rust's API documentation comes with the source code and you are +//! While you are looking at that `[-]` button also notice the `source` +//! link. Rust's API documentation comes with the source code and you are //! encouraged to read it. The standard library source is generally high //! quality and a peek behind the curtains is often enlightening. //! diff --git a/src/librustdoc/html/render/context.rs b/src/librustdoc/html/render/context.rs index 534a542d58ed0..2ae203e0d2f88 100644 --- a/src/librustdoc/html/render/context.rs +++ b/src/librustdoc/html/render/context.rs @@ -65,7 +65,7 @@ crate struct Context<'tcx> { /// /// [#82381]: https://github.com/rust-lang/rust/issues/82381 crate shared: Rc>, - /// This flag indicates whether `[src]` links should be generated or not. If + /// This flag indicates whether source links should be generated or not. If /// the source files are present in the html rendering, then this will be /// `true`. crate include_sources: bool, diff --git a/src/librustdoc/html/render/mod.rs b/src/librustdoc/html/render/mod.rs index 16334890da674..1af847b81d507 100644 --- a/src/librustdoc/html/render/mod.rs +++ b/src/librustdoc/html/render/mod.rs @@ -182,7 +182,7 @@ impl StylePath { fn write_srclink(cx: &Context<'_>, item: &clean::Item, buf: &mut Buffer) { if let Some(l) = cx.src_href(item) { - write!(buf, "[src]", l) + write!(buf, "source", l) } } @@ -807,7 +807,7 @@ fn render_stability_since_raw( const_stability: Option, containing_ver: Option, containing_const_ver: Option, -) { +) -> bool { let ver = ver.filter(|inner| !inner.is_empty()); match (ver, const_stability) { @@ -850,8 +850,9 @@ fn render_stability_since_raw( v ); } - _ => {} + _ => return false, } + true } fn render_assoc_item( @@ -1640,7 +1641,7 @@ fn render_impl( } // Render the items that appear on the right side of methods, impls, and -// associated types. For example "1.0.0 (const: 1.39.0) [src]". +// associated types. For example "1.0.0 (const: 1.39.0) · source". fn render_rightside( w: &mut Buffer, cx: &Context<'_>, @@ -1658,13 +1659,16 @@ fn render_rightside( }; write!(w, "
"); - render_stability_since_raw( + let has_stability = render_stability_since_raw( w, item.stable_since(tcx), const_stability, containing_item.stable_since(tcx), const_stable_since, ); + if has_stability { + w.write_str(" · "); + } write_srclink(cx, item, w); w.write_str("
"); diff --git a/src/librustdoc/html/render/print_item.rs b/src/librustdoc/html/render/print_item.rs index 44a9ec5ea4210..9f2830ba54215 100644 --- a/src/librustdoc/html/render/print_item.rs +++ b/src/librustdoc/html/render/print_item.rs @@ -108,10 +108,10 @@ pub(super) fn print_item( ); let stability_since_raw: String = stability_since_raw.into_inner(); - // Write `src` tag + // Write source tag // // When this item is part of a `crate use` in a downstream crate, the - // [src] link in the downstream documentation will actually come back to + // source link in the downstream documentation will actually come back to // this page, and this link will be auto-clicked. The `id` attribute is // used to find the link to auto-click. let src_href = @@ -1467,7 +1467,7 @@ fn render_stability_since( item.const_stability(tcx), containing_item.stable_since(tcx), containing_item.const_stable_since(tcx), - ) + ); } fn compare_impl<'a, 'b>(lhs: &'a &&Impl, rhs: &'b &&Impl, cx: &Context<'_>) -> Ordering { diff --git a/src/librustdoc/html/static/css/rustdoc.css b/src/librustdoc/html/static/css/rustdoc.css index d82c65398b835..49c0726dbca03 100644 --- a/src/librustdoc/html/static/css/rustdoc.css +++ b/src/librustdoc/html/static/css/rustdoc.css @@ -137,17 +137,25 @@ h1, h2, h3, h4 { margin: 15px 0 5px 0; } h1.fqn { + margin: 0; + padding: 0; +} +.main-heading { display: flex; - border-bottom: 1px dashed; - margin-top: 0; + border-bottom: 1px dashed #DDDDDD; + padding-bottom: 6px; + margin-bottom: 15px; /* workaround to keep flex from breaking below 700 px width due to the float: right on the nav above the h1 */ padding-left: 1px; } -h1.fqn > .in-band > a:hover { +.main-heading a:hover { text-decoration: underline; } +#toggle-all-docs { + text-decoration: none; +} /* The only headings that get underlines are: Markdown-generated headings within the top-doc Rustdoc-generated h2 section headings (e.g. "Implementations", "Required Methods", etc) @@ -195,11 +203,13 @@ h1, h2, h3, h4, h5, h6, .sidebar, a.source, .search-input, .search-results .result-name, .content table td:first-child > a, .item-left > a, -div.item-list .out-of-band, span.since, +.out-of-band, +span.since, #source-sidebar, #sidebar-toggle, details.rustdoc-toggle > summary::before, div.impl-items > div:not(.docblock):not(.item-info), -.content ul.crate a.crate, a.srclink, +.content ul.crate a.crate, +a.srclink, /* This selector is for the items listed in the "all items" page. */ #main-content > ul.docblock > li > a { font-family: "Fira Sans", Arial, NanumBarunGothic, sans-serif; @@ -605,10 +615,12 @@ nav.sub { .content .out-of-band { flex-grow: 0; text-align: right; - font-size: 1.4375rem; - margin: 0px; + margin-left: auto; + margin-right: 0; + font-size: 1.15rem; padding: 0 0 0 12px; font-weight: normal; + float: right; } .method > .code-header, .trait-impl > .code-header, .invisible > .code-header { @@ -1072,7 +1084,7 @@ body.blur > :not(#help) { font-size: initial; } -.impl-items .since, .impl .since, .methods .since { +.rightside { padding-left: 12px; padding-right: 2px; position: initial; @@ -1144,10 +1156,6 @@ a.test-arrow:hover{ font-weight: 300; } -.since + .srclink { - padding-left: 10px; -} - .item-spacer { width: 100%; height: 12px; diff --git a/src/librustdoc/html/static/css/themes/ayu.css b/src/librustdoc/html/static/css/themes/ayu.css index 38040eeca52d4..39df523c9d50e 100644 --- a/src/librustdoc/html/static/css/themes/ayu.css +++ b/src/librustdoc/html/static/css/themes/ayu.css @@ -222,7 +222,7 @@ nav.main .separator { a { color: #39AFD7; } -a.srclink, + a#toggle-all-docs, a.anchor, .small-section-header a, diff --git a/src/librustdoc/html/static/css/themes/dark.css b/src/librustdoc/html/static/css/themes/dark.css index f4181e431c896..35fde2b275eb7 100644 --- a/src/librustdoc/html/static/css/themes/dark.css +++ b/src/librustdoc/html/static/css/themes/dark.css @@ -180,7 +180,7 @@ nav.main .separator { a { color: #D2991D; } -a.srclink, + a#toggle-all-docs, a.anchor, .small-section-header a, diff --git a/src/librustdoc/html/static/css/themes/light.css b/src/librustdoc/html/static/css/themes/light.css index 176f63098a49f..e777285d9ea1c 100644 --- a/src/librustdoc/html/static/css/themes/light.css +++ b/src/librustdoc/html/static/css/themes/light.css @@ -177,7 +177,7 @@ nav.main .separator { a { color: #3873AD; } -a.srclink, + a#toggle-all-docs, a.anchor, .small-section-header a, @@ -243,10 +243,6 @@ details.undocumented > summary::before { border-color: #bfbfbf; } -.since { - color: grey; -} - .result-name .primitive > i, .result-name .keyword > i { color: black; } diff --git a/src/librustdoc/html/templates/print_item.html b/src/librustdoc/html/templates/print_item.html index 5a468f3cc1ea0..09cd8513a6453 100644 --- a/src/librustdoc/html/templates/print_item.html +++ b/src/librustdoc/html/templates/print_item.html @@ -1,26 +1,28 @@ -

{#- -#} - {#- -#} - {{-typ-}} - {#- The breadcrumbs of the item path, like std::string -#} - {%- for component in path_components -%} - {{component.name}}:: - {%- endfor -%} - {{name}} {#- -#} - {#- -#} - {#- -#} - {#- -#} - {{- stability_since_raw | safe -}} - {#- -#} - {#- -#} - [−] {#- -#} - {#- -#} +
+

{#- -#} + {#- -#} + {{-typ-}} + {#- The breadcrumbs of the item path, like std::string -#} + {%- for component in path_components -%} + {{component.name}}:: + {%- endfor -%} + {{name}} {#- -#} + {#- -#} {#- -#} - {%- if src_href -%} - [src] - {%- endif -%} +

{#- -#} + {#- -#} + {% if stability_since_raw %} + {{- stability_since_raw | safe -}} · + {% endif %} + {%- if src_href %} + source · + {% endif -%} + {#- -#} + [−] {#- -#} + {#- -#} {#- -#} -

{#- -#} + diff --git a/src/test/rustdoc-gui/anchors.goml b/src/test/rustdoc-gui/anchors.goml index ca60be72cea46..e6758287d8cb2 100644 --- a/src/test/rustdoc-gui/anchors.goml +++ b/src/test/rustdoc-gui/anchors.goml @@ -13,8 +13,10 @@ reload: assert-css: ("#toggle-all-docs", {"color": "rgb(0, 0, 0)"}) assert-css: (".fqn .in-band a:nth-of-type(1)", {"color": "rgb(0, 0, 0)"}) assert-css: (".fqn .in-band a:nth-of-type(2)", {"color": "rgb(173, 55, 138)"}) -assert-css: (".srclink", {"color": "rgb(0, 0, 0)"}) -assert-css: (".srclink", {"color": "rgb(0, 0, 0)"}) +assert-css: (".srclink", {"color": "rgb(56, 115, 173)"}) + +move-cursor-to: ".main-heading .srclink" +assert-css: (".srclink", {"text-decoration": "underline solid rgb(56, 115, 173)"}) assert-css: ("#top-doc-prose-title", {"color": "rgb(0, 0, 0)"}) diff --git a/src/test/rustdoc-gui/headings.goml b/src/test/rustdoc-gui/headings.goml index 87c512468e05f..9db75c59d948a 100644 --- a/src/test/rustdoc-gui/headings.goml +++ b/src/test/rustdoc-gui/headings.goml @@ -15,7 +15,7 @@ goto: file://|DOC_PATH|/test_docs/struct.HeavilyDocumentedStruct.html assert-css: ("h1.fqn", {"font-size": "24px"}) -assert-css: ("h1.fqn", {"border-bottom-width": "1px"}) +assert-css: (".main-heading", {"border-bottom-width": "1px"}) assert-css: ("h2#top-doc-prose-title", {"font-size": "20.8px"}) assert-css: ("h2#top-doc-prose-title", {"border-bottom-width": "1px"}) @@ -55,7 +55,7 @@ assert-css: ("h6#sub-sub-heading-for-struct-impl-item-doc", {"font-size": "15.2p goto: file://|DOC_PATH|/test_docs/enum.HeavilyDocumentedEnum.html assert-css: ("h1.fqn", {"font-size": "24px"}) -assert-css: ("h1.fqn", {"border-bottom-width": "1px"}) +assert-css: (".main-heading", {"border-bottom-width": "1px"}) assert-css: ("h2#top-doc-prose-title", {"font-size": "20.8px"}) assert-css: ("h2#top-doc-prose-title", {"border-bottom-width": "1px"}) @@ -115,7 +115,7 @@ assert-css: (".sidebar .others h3", {"border-bottom-width": "1px"}, ALL) goto: file://|DOC_PATH|/test_docs/union.HeavilyDocumentedUnion.html assert-css: ("h1.fqn", {"font-size": "24px"}) -assert-css: ("h1.fqn", {"border-bottom-width": "1px"}) +assert-css: (".main-heading", {"border-bottom-width": "1px"}) assert-css: ("h2#top-doc-prose-title", {"font-size": "20.8px"}) assert-css: ("h2#top-doc-prose-title", {"border-bottom-width": "1px"}) @@ -148,7 +148,7 @@ assert-css: ("h6#sub-heading-for-union-impl-item-doc", {"border-bottom-width": " goto: file://|DOC_PATH|/test_docs/macro.heavily_documented_macro.html assert-css: ("h1.fqn", {"font-size": "24px"}) -assert-css: ("h1.fqn", {"border-bottom-width": "1px"}) +assert-css: (".main-heading", {"border-bottom-width": "1px"}) assert-css: ("h2#top-doc-prose-title", {"font-size": "20.8px"}) assert-css: ("h2#top-doc-prose-title", {"border-bottom-width": "1px"}) diff --git a/src/test/rustdoc-gui/toggle-docs.goml b/src/test/rustdoc-gui/toggle-docs.goml index eaa4c554d5a0f..e11aae21e3fa6 100644 --- a/src/test/rustdoc-gui/toggle-docs.goml +++ b/src/test/rustdoc-gui/toggle-docs.goml @@ -1,10 +1,13 @@ goto: file://|DOC_PATH|/test_docs/index.html assert-attribute: ("#main-content > details.top-doc", {"open": ""}) +assert-text: ("#toggle-all-docs", "[−]") click: "#toggle-all-docs" wait-for: 1000 // This is now collapsed so there shouldn't be the "open" attribute on details. assert-attribute-false: ("#main-content > details.top-doc", {"open": ""}) +assert-text: ("#toggle-all-docs", "[+]") click: "#toggle-all-docs" wait-for: 1000 // Not collapsed anymore so the "open" attribute should be back. assert-attribute: ("#main-content > details.top-doc", {"open": ""}) +assert-text: ("#toggle-all-docs", "[−]") diff --git a/src/test/rustdoc/ensure-src-link.rs b/src/test/rustdoc/ensure-src-link.rs index 6189acb72542a..d32d3fc581f8a 100644 --- a/src/test/rustdoc/ensure-src-link.rs +++ b/src/test/rustdoc/ensure-src-link.rs @@ -2,5 +2,5 @@ // This test ensures that the [src] link is present on traits items. -// @has foo/trait.Iterator.html '//div[@id="method.zip"]//a[@class="srclink"]' "[src]" +// @has foo/trait.Iterator.html '//div[@id="method.zip"]//a[@class="srclink"]' "source" pub use std::iter::Iterator; diff --git a/src/test/rustdoc/external-macro-src.rs b/src/test/rustdoc/external-macro-src.rs index 6a7dbb004a362..359551ab78d1e 100644 --- a/src/test/rustdoc/external-macro-src.rs +++ b/src/test/rustdoc/external-macro-src.rs @@ -5,8 +5,8 @@ #[macro_use] extern crate external_macro_src; -// @has foo/index.html '//a[@href="../src/foo/external-macro-src.rs.html#3-12"]' '[src]' +// @has foo/index.html '//a[@href="../src/foo/external-macro-src.rs.html#3-12"]' 'source' // @has foo/struct.Foo.html -// @has - '//a[@href="../src/foo/external-macro-src.rs.html#12"]' '[src]' +// @has - '//a[@href="../src/foo/external-macro-src.rs.html#12"]' 'source' make_foo!(); diff --git a/src/test/rustdoc/issue-16265-1.rs b/src/test/rustdoc/issue-16265-1.rs index 653fd4c5e34e6..ec007e36b726c 100644 --- a/src/test/rustdoc/issue-16265-1.rs +++ b/src/test/rustdoc/issue-16265-1.rs @@ -1,8 +1,10 @@ pub struct Foo; -// @has issue_16265_1/traits/index.html '[src]' +// @has issue_16265_1/traits/index.html 'source' pub mod traits { impl PartialEq for super::Foo { - fn eq(&self, _: &super::Foo) -> bool { true } + fn eq(&self, _: &super::Foo) -> bool { + true + } } } diff --git a/src/test/rustdoc/issue-16265-2.rs b/src/test/rustdoc/issue-16265-2.rs index 00453a3633328..d5cd18d9daf9d 100644 --- a/src/test/rustdoc/issue-16265-2.rs +++ b/src/test/rustdoc/issue-16265-2.rs @@ -1,4 +1,4 @@ -// @has issue_16265_2/index.html '[src]' +// @has issue_16265_2/index.html 'source' trait Y {} -impl Y for Option{} +impl Y for Option {} diff --git a/src/test/rustdoc/issue-26606.rs b/src/test/rustdoc/issue-26606.rs index bd6f38e912338..d5cb2c710cde8 100644 --- a/src/test/rustdoc/issue-26606.rs +++ b/src/test/rustdoc/issue-26606.rs @@ -7,5 +7,5 @@ extern crate issue_26606_macro; // @has issue_26606/constant.FOO.html -// @has - '//a[@href="../src/issue_26606/issue-26606.rs.html#11"]' '[src]' +// @has - '//a[@href="../src/issue_26606/issue-26606.rs.html#11"]' 'source' make_item!(FOO); diff --git a/src/test/rustdoc/src-links-auto-impls.rs b/src/test/rustdoc/src-links-auto-impls.rs index f9ac836c9b18f..46b8778217d27 100644 --- a/src/test/rustdoc/src-links-auto-impls.rs +++ b/src/test/rustdoc/src-links-auto-impls.rs @@ -2,11 +2,11 @@ // @has foo/struct.Unsized.html // @has - '//div[@id="impl-Sized"]/h3[@class="code-header in-band"]' 'impl !Sized for Unsized' -// @!has - '//div[@id="impl-Sized"]//a[@class="srclink"]' '[src]' +// @!has - '//div[@id="impl-Sized"]//a[@class="srclink"]' 'source' // @has - '//div[@id="impl-Sync"]/h3[@class="code-header in-band"]' 'impl Sync for Unsized' -// @!has - '//div[@id="impl-Sync"]//a[@class="srclink"]' '[src]' +// @!has - '//div[@id="impl-Sync"]//a[@class="srclink"]' 'source' // @has - '//div[@id="impl-Any"]/h3[@class="code-header in-band"]' 'impl Any for T' -// @has - '//div[@id="impl-Any"]//a[@class="srclink"]' '[src]' +// @has - '//div[@id="impl-Any"]//a[@class="srclink"]' 'source' pub struct Unsized { data: [u8], } diff --git a/src/test/rustdoc/thread-local-src.rs b/src/test/rustdoc/thread-local-src.rs index 5e56bb5819a10..6de35e3233b05 100644 --- a/src/test/rustdoc/thread-local-src.rs +++ b/src/test/rustdoc/thread-local-src.rs @@ -1,6 +1,6 @@ #![crate_name = "foo"] -// @has foo/index.html '//a[@href="../src/foo/thread-local-src.rs.html#1-6"]' '[src]' +// @has foo/index.html '//a[@href="../src/foo/thread-local-src.rs.html#1-6"]' 'source' -// @has foo/constant.FOO.html '//a[@href="../src/foo/thread-local-src.rs.html#6"]' '[src]' +// @has foo/constant.FOO.html '//a[@href="../src/foo/thread-local-src.rs.html#6"]' 'source' thread_local!(pub static FOO: bool = false); diff --git a/src/test/rustdoc/trait-src-link.rs b/src/test/rustdoc/trait-src-link.rs index 77116695690fc..a6367efba6121 100644 --- a/src/test/rustdoc/trait-src-link.rs +++ b/src/test/rustdoc/trait-src-link.rs @@ -1,26 +1,26 @@ #![crate_name = "quix"] pub trait Foo { - // @has quix/trait.Foo.html '//a[@href="../src/quix/trait-src-link.rs.html#4"]' '[src]' + // @has quix/trait.Foo.html '//a[@href="../src/quix/trait-src-link.rs.html#4"]' 'source' fn required(); - // @has quix/trait.Foo.html '//a[@href="../src/quix/trait-src-link.rs.html#7"]' '[src]' + // @has quix/trait.Foo.html '//a[@href="../src/quix/trait-src-link.rs.html#7"]' 'source' fn provided() {} } pub struct Bar; impl Foo for Bar { - // @has quix/struct.Bar.html '//a[@href="../src/quix/trait-src-link.rs.html#14"]' '[src]' + // @has quix/struct.Bar.html '//a[@href="../src/quix/trait-src-link.rs.html#14"]' 'source' fn required() {} - // @has quix/struct.Bar.html '//a[@href="../src/quix/trait-src-link.rs.html#7"]' '[src]' + // @has quix/struct.Bar.html '//a[@href="../src/quix/trait-src-link.rs.html#7"]' 'source' } pub struct Baz; impl Foo for Baz { - // @has quix/struct.Baz.html '//a[@href="../src/quix/trait-src-link.rs.html#22"]' '[src]' + // @has quix/struct.Baz.html '//a[@href="../src/quix/trait-src-link.rs.html#22"]' 'source' fn required() {} - // @has quix/struct.Baz.html '//a[@href="../src/quix/trait-src-link.rs.html#25"]' '[src]' + // @has quix/struct.Baz.html '//a[@href="../src/quix/trait-src-link.rs.html#25"]' 'source' fn provided() {} }