From def144c2e752cf2040d21fbd0cf04f5779cce898 Mon Sep 17 00:00:00 2001 From: Jacob Hoffman-Andrews Date: Sat, 27 Mar 2021 12:50:09 -0700 Subject: [PATCH] Improve CSS for "hide contents, not items" Introduce a first use of the `
` and `` tags as replacements for the JS-built toggles. I think this has the potential to replace all the JS toggles and generally clean up the JS, CSS, and HTML. Split rendering of attributes into two cases: in the case where they are rendered as descendents of a `
` tag, where they use indent spaces and
newlines for formatting, matching their surrounding markup. In the case
where they are rendered as descendants of a `` tag, they are
rendered as `
`. This let me clean up some fragile CSS that was adjusting the margin-left of attributes depending on context. Remove toggles for attributes. With the ALLOWED_ATTRIBUTES filter, it's rare for an item to have more than one attribute, so hiding attributes behind a toggle doesn't save any screen space in the common case. Fix a couple of invocations of `matches!` that didn't compile on my machine. Fix a boolean for the JS `createToggle` call that was causing "Expand description" to show up spuriously on already-expanded descriptions. Add JS for auto-hide settings and hide all / show all. Remove a z-index property and some font color tweaks made unnecessary by the
toggles. Add CSS for the
toggles. --- src/librustdoc/html/render/mod.rs | 52 +++++++------ src/librustdoc/html/render/print_item.rs | 46 ++++++------ src/librustdoc/html/static/main.js | 58 ++++---------- src/librustdoc/html/static/rustdoc.css | 83 ++++++++++++--------- src/librustdoc/html/static/storage.js | 1 - src/librustdoc/html/static/themes/ayu.css | 2 +- src/librustdoc/html/static/themes/dark.css | 2 +- src/librustdoc/html/static/themes/light.css | 2 +- 8 files changed, 116 insertions(+), 130 deletions(-) diff --git a/src/librustdoc/html/render/mod.rs b/src/librustdoc/html/render/mod.rs index 00a19006bb9..d0d9034f6e6 100644 --- a/src/librustdoc/html/render/mod.rs +++ b/src/librustdoc/html/render/mod.rs @@ -43,7 +43,6 @@ use std::path::PathBuf; use std::str; use std::string::ToString; -use itertools::Itertools; use rustc_ast_pretty::pprust; use rustc_attr::{Deprecation, StabilityLevel}; use rustc_data_structures::fx::FxHashSet; @@ -487,7 +486,6 @@ fn settings(root_path: &str, suffix: &str, themes: &[StylePath]) -> Result{".len() + "".len()); write!( w, "{}{}{}{}{}{}{}fn {name}\ {generics}{decl}{notable_traits}{where_clause}", - if parent == ItemType::Trait { " " } else { "" }, + indent_str, vis, constness, asyncness, @@ -1004,35 +1004,33 @@ const ALLOWED_ATTRIBUTES: &[Symbol] = &[ sym::non_exhaustive, ]; -// The `top` parameter is used when generating the item declaration to ensure it doesn't have a -// left padding. For example: -// -// #[foo] <----- "top" attribute -// struct Foo { -// #[bar] <---- not "top" attribute -// bar: usize, -// } -fn render_attributes(w: &mut Buffer, it: &clean::Item, top: bool) { - let attrs = it - .attrs +fn attributes(it: &clean::Item) -> Vec { + it.attrs .other_attrs .iter() .filter_map(|attr| { if ALLOWED_ATTRIBUTES.contains(&attr.name_or_empty()) { - Some(pprust::attribute_to_string(&attr)) + Some(pprust::attribute_to_string(&attr).replace("\n", "").replace(" ", " ")) } else { None } }) - .join("\n"); + .collect() +} - if !attrs.is_empty() { - write!( - w, - "{}", - if top { " top-attr" } else { "" }, - &attrs - ); +// When an attribute is rendered inside a `
` tag, it is formatted using
+// a whitespace prefix and newline.
+fn render_attributes_in_pre(w: &mut Buffer, it: &clean::Item, prefix: &str) {
+    for a in attributes(it) {
+        write!(w, "{}{}\n", prefix, a);
+    }
+}
+
+// When an attribute is rendered inside a  tag, it is formatted using
+// a div to produce a newline after it.
+fn render_attributes_in_code(w: &mut Buffer, it: &clean::Item) {
+    for a in attributes(it) {
+        write!(w, "
{}
", a); } } diff --git a/src/librustdoc/html/render/print_item.rs b/src/librustdoc/html/render/print_item.rs index d5a5ecd3e88..03c4bb837f5 100644 --- a/src/librustdoc/html/render/print_item.rs +++ b/src/librustdoc/html/render/print_item.rs @@ -11,8 +11,8 @@ use rustc_span::symbol::{kw, sym, Symbol}; use super::{ collect_paths_for_type, document, ensure_trailing_slash, item_ty_to_strs, notable_traits_decl, - render_assoc_item, render_assoc_items, render_attributes, render_impl, - render_stability_since_raw, write_srclink, AssocItemLink, Context, + render_assoc_item, render_assoc_items, render_attributes_in_code, render_attributes_in_pre, + render_impl, render_stability_since_raw, write_srclink, AssocItemLink, Context, }; use crate::clean::{self, GetDefId}; use crate::formats::cache::Cache; @@ -138,11 +138,15 @@ fn should_hide_fields(n_fields: usize) -> bool { } fn toggle_open(w: &mut Buffer, text: &str) { - write!(w, "
", text); + write!( + w, + "
Show {}", + text + ); } fn toggle_close(w: &mut Buffer) { - w.write_str("
"); + w.write_str("
"); } fn item_module(w: &mut Buffer, cx: &Context<'_>, item: &clean::Item, items: &[clean::Item]) { @@ -391,7 +395,7 @@ fn item_function(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, f: &clean:: ) .len(); w.write_str("
");
-    render_attributes(w, it, false);
+    render_attributes_in_pre(w, it, "");
     write!(
         w,
         "{vis}{constness}{asyncness}{unsafety}{abi}fn \
@@ -420,7 +424,7 @@ fn item_trait(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, t: &clean::Tra
     // Output the trait definition
     wrap_into_docblock(w, |w| {
         w.write_str("
");
-        render_attributes(w, it, true);
+        render_attributes_in_pre(w, it, "");
         write!(
             w,
             "{}{}{}trait {}{}{}",
@@ -729,7 +733,7 @@ fn item_trait(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, t: &clean::Tra
 
 fn item_trait_alias(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, t: &clean::TraitAlias) {
     w.write_str("
");
-    render_attributes(w, it, false);
+    render_attributes_in_pre(w, it, "");
     write!(
         w,
         "trait {}{}{} = {};
", @@ -750,7 +754,7 @@ fn item_trait_alias(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, t: &clea fn item_opaque_ty(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, t: &clean::OpaqueTy) { w.write_str("
");
-    render_attributes(w, it, false);
+    render_attributes_in_pre(w, it, "");
     write!(
         w,
         "type {}{}{where_clause} = impl {bounds};
", @@ -771,7 +775,7 @@ fn item_opaque_ty(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, t: &clean: fn item_typedef(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, t: &clean::Typedef) { w.write_str("
");
-    render_attributes(w, it, false);
+    render_attributes_in_pre(w, it, "");
     write!(
         w,
         "type {}{}{where_clause} = {type_};
", @@ -793,7 +797,7 @@ fn item_typedef(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, t: &clean::T fn item_union(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, s: &clean::Union) { wrap_into_docblock(w, |w| { w.write_str("
");
-        render_attributes(w, it, true);
+        render_attributes_in_pre(w, it, "");
         render_union(w, it, Some(&s.generics), &s.fields, "", true, cx);
         w.write_str("
") }); @@ -839,7 +843,7 @@ fn item_union(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, s: &clean::Uni fn item_enum(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, e: &clean::Enum) { wrap_into_docblock(w, |w| { w.write_str("
");
-        render_attributes(w, it, true);
+        render_attributes_in_pre(w, it, "");
         write!(
             w,
             "{}enum {}{}{}",
@@ -1019,7 +1023,7 @@ fn item_primitive(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item) {
 
 fn item_constant(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, c: &clean::Constant) {
     w.write_str("
");
-    render_attributes(w, it, false);
+    render_attributes_in_code(w, it);
 
     write!(
         w,
@@ -1058,7 +1062,7 @@ fn item_constant(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, c: &clean::
 fn item_struct(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, s: &clean::Struct) {
     wrap_into_docblock(w, |w| {
         w.write_str("
");
-        render_attributes(w, it, true);
+        render_attributes_in_code(w, it);
         render_struct(w, it, Some(&s.generics), s.struct_type, &s.fields, "", true, cx);
         w.write_str("
") }); @@ -1107,7 +1111,7 @@ fn item_struct(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, s: &clean::St fn item_static(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, s: &clean::Static) { w.write_str("
");
-    render_attributes(w, it, false);
+    render_attributes_in_code(w, it);
     write!(
         w,
         "{vis}static {mutability}{name}: {typ}
", @@ -1121,7 +1125,7 @@ fn item_static(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, s: &clean::St fn item_foreign_type(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item) { w.write_str("
extern {\n");
-    render_attributes(w, it, false);
+    render_attributes_in_code(w, it);
     write!(
         w,
         "    {}type {};\n}}
", @@ -1304,10 +1308,8 @@ fn render_union( } write!(w, " {{\n{}", tab); - let count_fields = fields - .iter() - .filter(|f| matches!(clean::StructFieldItem(..), *f.kind)) - .count(); + let count_fields = + fields.iter().filter(|f| matches!(*f.kind, clean::StructFieldItem(..))).count(); let toggle = should_hide_fields(count_fields); if toggle { toggle_open(w, "fields"); @@ -1361,10 +1363,8 @@ fn render_struct( write!(w, "{}", print_where_clause(g, cx.cache(), cx.tcx(), 0, true),) } w.write_str(" {"); - let count_fields = fields - .iter() - .filter(|f| matches!(clean::StructFieldItem(..) = *f.kind)) - .count(); + let count_fields = + fields.iter().filter(|f| matches!(*f.kind, clean::StructFieldItem(..))).count(); let has_visible_fields = count_fields > 0; let toggle = should_hide_fields(count_fields); if toggle { diff --git a/src/librustdoc/html/static/main.js b/src/librustdoc/html/static/main.js index af66a7a135a..1b14f67fce1 100644 --- a/src/librustdoc/html/static/main.js +++ b/src/librustdoc/html/static/main.js @@ -1,4 +1,3 @@ -// ignore-tidy-filelength // Local js definitions: /* global addClass, getSettingValue, hasClass */ /* global onEach, onEachLazy, hasOwnProperty, removeClass, updateLocalStorage */ @@ -2316,6 +2315,9 @@ function hideThemeButtonState() { if (hasClass(innerToggle, "will-expand")) { updateLocalStorage("rustdoc-collapse", "false"); removeClass(innerToggle, "will-expand"); + onEachLazy(document.getElementsByTagName("details"), function(e) { + e.open = true; + }); onEveryMatchingChild(innerToggle, "inner", function(e) { e.innerHTML = labelForToggleButton(false); }); @@ -2328,6 +2330,9 @@ function hideThemeButtonState() { } else { updateLocalStorage("rustdoc-collapse", "true"); addClass(innerToggle, "will-expand"); + onEachLazy(document.getElementsByTagName("details"), function(e) { + e.open = false; + }); onEveryMatchingChild(innerToggle, "inner", function(e) { var parent = e.parentNode; var superParent = null; @@ -2569,6 +2574,7 @@ function hideThemeButtonState() { var toggle = createSimpleToggle(false); var hideMethodDocs = getSettingValue("auto-hide-method-docs") === "true"; var hideImplementors = getSettingValue("auto-collapse-implementors") !== "false"; + let hideLargeItemContents = getSettingValue("auto-hide-large-items") !== "false"; var func = function(e) { var next = e.nextElementSibling; @@ -2615,6 +2621,14 @@ function hideThemeButtonState() { onEachLazy(document.getElementsByClassName("associatedconstant"), func); onEachLazy(document.getElementsByClassName("impl"), funcImpl); var impl_call = function() {}; + // Large items are hidden by default in the HTML. If the setting overrides that, show 'em. + if (!hideLargeItemContents) { + onEachLazy(document.getElementsByTagName("details"), function (e) { + if (hasClass(e, "type-contents-toggle")) { + e.open = true; + } + }); + } if (hideMethodDocs === true) { impl_call = function(e, newToggle) { if (e.id.match(/^impl(?:-\d+)?$/) === null) { @@ -2703,14 +2717,6 @@ function hideThemeButtonState() { } }); } - } else if (hasClass(e, "type-contents-toggle")) { - let text = e.getAttribute("data-toggle-text"); - let hideItemContents = getSettingValue("auto-hide-large-items") !== "false"; - let tog = createToggle(toggle, `Show ${text}`, null, "", !hideItemContents); - e.parentNode.insertBefore(tog, e); - if (hideItemContents) { - collapseDocs(e.previousSibling.childNodes[0], "toggle"); - } } if (e.parentNode.id === "main") { var otherMessage = ""; @@ -2744,7 +2750,7 @@ function hideThemeButtonState() { otherMessage, fontSize, extraClass, - false), + true), e); if (hasClass(e, "non-exhaustive") === true) { collapseDocs(e.previousSibling.childNodes[0], "toggle"); @@ -2763,38 +2769,6 @@ function hideThemeButtonState() { } }()); - function createToggleWrapper(tog) { - var span = document.createElement("span"); - span.className = "toggle-label"; - span.style.display = "none"; - span.innerHTML = " Expand attributes"; - tog.appendChild(span); - - var wrapper = document.createElement("div"); - wrapper.className = "toggle-wrapper toggle-attributes"; - wrapper.appendChild(tog); - return wrapper; - } - - (function() { - // To avoid checking on "rustdoc-item-attributes" value on every loop... - var itemAttributesFunc = function() {}; - if (getSettingValue("auto-hide-attributes") !== "false") { - itemAttributesFunc = function(x) { - collapseDocs(x.previousSibling.childNodes[0], "toggle"); - }; - } - var attributesToggle = createToggleWrapper(createSimpleToggle(false)); - onEachLazy(main.getElementsByClassName("attributes"), function(i_e) { - var attr_tog = attributesToggle.cloneNode(true); - if (hasClass(i_e, "top-attr") === true) { - addClass(attr_tog, "top-attr"); - } - i_e.parentNode.insertBefore(attr_tog, i_e); - itemAttributesFunc(i_e); - }); - }()); - (function() { // To avoid checking on "rustdoc-line-numbers" value on every loop... var lineNumbersFunc = function() {}; diff --git a/src/librustdoc/html/static/rustdoc.css b/src/librustdoc/html/static/rustdoc.css index 309e55670b1..64972bc2389 100644 --- a/src/librustdoc/html/static/rustdoc.css +++ b/src/librustdoc/html/static/rustdoc.css @@ -970,10 +970,6 @@ a.test-arrow:hover{ position: absolute; left: -23px; top: 0; - - /* The click event for this is defined on the document, - so bubbling does not work. See https://github.com/rust-lang/rust/issues/83332 */ - z-index: 10; } h3 > .collapse-toggle, h4 > .collapse-toggle { @@ -1058,11 +1054,6 @@ h3 > .collapse-toggle, h4 > .collapse-toggle { margin-top: 3px; } -/* for hiding fields/variants/associated items */ -.enum > .toggle-wrapper + .docblock, .struct > .toggle-wrapper + .docblock, .union > .toggle-wrapper + .docblock, .trait > .toggle-wrapper + .docblock { - margin-left: 0px; -} - .docblock > .section-header:first-child { margin-left: 15px; margin-top: 0; @@ -1076,22 +1067,6 @@ h3 > .collapse-toggle, h4 > .collapse-toggle { display: block; } -.attributes { - display: block; - margin-top: 0px !important; - margin-right: 0px; - margin-bottom: 0px !important; - margin-left: 30px; -} -.toggle-attributes.collapsed { - margin-bottom: 0; -} -.impl-items > .toggle-attributes { - margin-left: 20px; -} -.impl-items .attributes { - font-weight: 500; -} :target > code { opacity: 1; @@ -1778,16 +1753,56 @@ div.name.expand::before { top: 2px; } -/* This part is to fix the "Expand attributes" part in the type declaration. */ -.type-decl > pre > .toggle-wrapper.toggle-attributes.top-attr { - margin-left: 0 !important; +/* The hideme class is used on summary tags that contain a span with + placeholder text shown only when the toggle is closed. For instance, + "Expand description" or "Show methods". */ +details > summary.hideme { + cursor: pointer; } -.type-decl > pre > .docblock.attributes.top-attr { - margin-left: 1.8em !important; + +details > summary::-webkit-details-marker { + display: none; } -.type-decl > pre .toggle-attributes { - margin-left: 2.2em; + +details > summary.hideme > span { + margin-left: 9px; + color: #999; } -.type-decl > pre > .docblock.attributes { - margin-left: 4em; + +details > summary::before { + content: "[+]"; + font-weight: 300; + font-size: 0.8em; + color: #999; + letter-spacing: 1px; +} + +details > summary.hideme::before { + position: relative; +} + +details > summary:not(.hideme)::before { + float: left; +} + +/* When a "hideme" summary is open and the "Expand description" or "Show + methods" text is hidden, we want the [-] toggle that remains to not + affect the layout of the items to its right. To do that, we use + absolute positioning. Note that we also set position: relative + on the parent
to make this work properly. */ +details[open] > summary.hideme { + position: absolute; +} + +details[open] { + position: relative; +} + +details[open] > summary.hideme > span { + display: none; +} + +details[open] > summary::before { + content: "[−]"; + display: inline; } diff --git a/src/librustdoc/html/static/storage.js b/src/librustdoc/html/static/storage.js index c68128516d2..2ed87fdedae 100644 --- a/src/librustdoc/html/static/storage.js +++ b/src/librustdoc/html/static/storage.js @@ -1,6 +1,5 @@ // From rust: /* global resourcesSuffix */ - var darkThemes = ["dark", "ayu"]; window.currentTheme = document.getElementById("themeStyle"); window.mainTheme = document.getElementById("mainThemeStyle"); diff --git a/src/librustdoc/html/static/themes/ayu.css b/src/librustdoc/html/static/themes/ayu.css index 0404fa50b99..b24f4035ca8 100644 --- a/src/librustdoc/html/static/themes/ayu.css +++ b/src/librustdoc/html/static/themes/ayu.css @@ -218,7 +218,7 @@ a { color: #c5c5c5; } -.docblock:not(.type-decl) a:not(.srclink):not(.test-arrow):not(.collapse-toggle), +.docblock:not(.type-decl) a:not(.srclink):not(.test-arrow), .docblock-short a:not(.srclink):not(.test-arrow), .item-info a, #help a { color: #39AFD7; diff --git a/src/librustdoc/html/static/themes/dark.css b/src/librustdoc/html/static/themes/dark.css index 15b485a966f..e863ed03f51 100644 --- a/src/librustdoc/html/static/themes/dark.css +++ b/src/librustdoc/html/static/themes/dark.css @@ -176,7 +176,7 @@ a { color: #ddd; } -.docblock:not(.type-decl) a:not(.srclink):not(.test-arrow):not(.collapse-toggle), +.docblock:not(.type-decl) a:not(.srclink):not(.test-arrow), .docblock-short a:not(.srclink):not(.test-arrow), .item-info a, #help a { color: #D2991D; diff --git a/src/librustdoc/html/static/themes/light.css b/src/librustdoc/html/static/themes/light.css index 4c83879e234..9335dd96d29 100644 --- a/src/librustdoc/html/static/themes/light.css +++ b/src/librustdoc/html/static/themes/light.css @@ -174,7 +174,7 @@ a { color: #000; } -.docblock:not(.type-decl) a:not(.srclink):not(.test-arrow):not(.collapse-toggle), +.docblock:not(.type-decl) a:not(.srclink):not(.test-arrow), .docblock-short a:not(.srclink):not(.test-arrow), .item-info a, #help a { color: #3873AD;