Skip to content

Migrate top doc and non-exhaustive toggles to details tag #85074

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.

Sign up for GitHub

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

Merged
merged 2 commits into from
May 10, 2021
Merged

Migrate top doc and non-exhaustive toggles to details tag #85074

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4edcf61
End toggle migration
GuillaumeGomez May 8, 2021
3837c1c
Update rustdoc test
GuillaumeGomez May 8, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 21 additions & 2 deletions src/librustdoc/html/render/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -509,7 +509,7 @@ fn document(w: &mut Buffer, cx: &Context<'_>, item: &clean::Item, parent: Option
info!("Documenting {}", name);
}
document_item_info(w, cx, item, parent);
document_full(w, item, cx);
document_full_collapsible(w, item, cx);
}

/// Render md_text as markdown.
Expand Down Expand Up @@ -561,10 +561,29 @@ fn document_short(
}
}

fn document_full_collapsible(w: &mut Buffer, item: &clean::Item, cx: &Context<'_>) {
document_full_inner(w, item, cx, true);
}

fn document_full(w: &mut Buffer, item: &clean::Item, cx: &Context<'_>) {
document_full_inner(w, item, cx, false);
}

fn document_full_inner(w: &mut Buffer, item: &clean::Item, cx: &Context<'_>, is_collapsible: bool) {
if let Some(s) = cx.shared.maybe_collapsed_doc_value(item) {
debug!("Doc block: =====\n{}\n=====", s);
render_markdown(w, cx, &s, item.links(cx));
if is_collapsible {
w.write_str(
"<details class=\"rustdoc-toggle top-doc\" open>\
<summary class=\"hideme\">\
<span>Expand description</span>\
</summary>",
);
render_markdown(w, cx, &s, item.links(cx));
w.write_str("</details>");
} else {
render_markdown(w, cx, &s, item.links(cx));
}
}
}

Expand Down
28 changes: 17 additions & 11 deletions src/librustdoc/html/render/print_item.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1464,17 +1464,23 @@ fn document_non_exhaustive_header(item: &clean::Item) -> &str {

fn document_non_exhaustive(w: &mut Buffer, item: &clean::Item) {
if item.is_non_exhaustive() {
write!(w, "<div class=\"docblock non-exhaustive non-exhaustive-{}\">", {
if item.is_struct() {
"struct"
} else if item.is_enum() {
"enum"
} else if item.is_variant() {
"variant"
} else {
"type"
write!(
w,
"<details class=\"rustdoc-toggle non-exhaustive\">\
<summary class=\"hideme\"><span>{}</span></summary>\
<div class=\"docblock\">",
{
if item.is_struct() {
"This struct is marked as non-exhaustive"
} else if item.is_enum() {
"This enum is marked as non-exhaustive"
} else if item.is_variant() {
"This variant is marked as non-exhaustive"
} else {
"This type is marked as non-exhaustive"
}
}
});
);

if item.is_struct() {
w.write_str(
Expand Down Expand Up @@ -1502,6 +1508,6 @@ fn document_non_exhaustive(w: &mut Buffer, item: &clean::Item) {
);
}

w.write_str("</div>");
w.write_str("</div></details>");
}
}
222 changes: 18 additions & 204 deletions src/librustdoc/html/static/main.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -377,28 +377,7 @@ function hideThemeButtonState() {
if (savedHash.length === 0) {
return;
}
elem = document.getElementById(savedHash.slice(1)); // we remove the '#'
if (!elem || !isHidden(elem)) {
return;
}
var parent = elem.parentNode;
if (parent && hasClass(parent, "impl-items")) {
// In case this is a trait implementation item, we first need to toggle
// the "Show hidden undocumented items".
onEachLazy(parent.getElementsByClassName("collapsed"), function(e) {
if (e.parentNode === parent) {
// Only click on the toggle we're looking for.
e.click();
return true;
}
});
if (isHidden(elem)) {
// The whole parent is collapsed. We need to click on its toggle as well!
if (hasClass(parent.lastElementChild, "collapse-toggle")) {
parent.lastElementChild.click();
}
}
}
expandSection(savedHash.slice(1)); // we remove the '#'
}
}

Expand Down Expand Up @@ -465,25 +444,7 @@ function hideThemeButtonState() {
}

function expandSection(id) {
var elem = document.getElementById(id);
if (elem && isHidden(elem)) {
var h3 = elem.parentNode.previousElementSibling;
if (h3 && h3.tagName !== "H3") {
h3 = h3.previousElementSibling; // skip div.docblock
}

if (h3) {
var collapses = h3.getElementsByClassName("collapse-toggle");
if (collapses.length > 0) {
// The element is not visible, we need to make it appear!
collapseDocs(collapses[0], "show");
}
// Open all ancestor <details> to make this element visible.
openParentDetails(h3.parentNode);
} else {
openParentDetails(elem.parentNode);
}
}
openParentDetails(document.getElementById(id));
}

function getHelpElement(build) {
Expand Down Expand Up @@ -678,10 +639,6 @@ function hideThemeButtonState() {
var helpElem = getHelpElement(false);
if (hasClass(ev.target, "help-button")) {
displayHelp(true, ev);
} else if (hasClass(ev.target, "collapse-toggle")) {
collapseDocs(ev.target, "toggle");
} else if (hasClass(ev.target.parentNode, "collapse-toggle")) {
collapseDocs(ev.target.parentNode, "toggle");
} else if (ev.target.tagName === "SPAN" && hasClass(ev.target.parentNode, "line-numbers")) {
handleSourceHighlight(ev);
} else if (helpElem && hasClass(helpElem, "hidden") === false) {
Expand Down Expand Up @@ -898,72 +855,34 @@ function hideThemeButtonState() {
return "\u2212"; // "\u2212" is "−" minus sign
}

function onEveryMatchingChild(elem, className, func) {
if (elem && className && func) {
var length = elem.childNodes.length;
var nodes = elem.childNodes;
for (var i = 0; i < length; ++i) {
if (hasClass(nodes[i], className)) {
func(nodes[i]);
} else {
onEveryMatchingChild(nodes[i], className, func);
}
}
}
}

function toggleAllDocs(fromAutoCollapse) {
function toggleAllDocs() {
var innerToggle = document.getElementById(toggleAllDocsId);
if (!innerToggle) {
return;
}
var sectionIsCollapsed = false;
if (hasClass(innerToggle, "will-expand")) {
removeClass(innerToggle, "will-expand");
onEachLazy(document.getElementsByTagName("details"), function(e) {
e.open = true;
});
onEveryMatchingChild(innerToggle, "inner", function(e) {
e.innerHTML = labelForToggleButton(false);
onEachLazy(document.getElementsByClassName("rustdoc-toggle"), function(e) {
if (!hasClass(e, "type-contents-toggle")) {
e.open = true;
}
});
innerToggle.title = "collapse all docs";
if (fromAutoCollapse !== true) {
onEachLazy(document.getElementsByClassName("collapse-toggle"), function(e) {
collapseDocs(e, "show");
});
}
} else {
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;

if (parent) {
superParent = parent.parentNode;
}
if (!parent || !superParent || superParent.id !== "main" ||
hasClass(parent, "impl") === false) {
e.innerHTML = labelForToggleButton(true);
onEachLazy(document.getElementsByClassName("rustdoc-toggle"), function(e) {
if (e.parentNode.id !== "main" ||
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why are direct children of main excluded from this?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Only the type declaration <details> and the impl blocks are ignored in this case (look in the or condition ;) ), like it's currently the case. I kept the same logic.

(!hasClass(e, "implementors-toggle") &&
!hasClass(e, "type-contents-toggle")))
{
e.open = false;
}
});
sectionIsCollapsed = true;
innerToggle.title = "expand all docs";
if (fromAutoCollapse !== true) {
onEachLazy(document.getElementsByClassName("collapse-toggle"), function(e) {
var parent = e.parentNode;
var superParent = null;

if (parent) {
superParent = parent.parentNode;
}
if (!parent || !superParent || superParent.id !== "main" ||
hasClass(parent, "impl") === false) {
collapseDocs(e, "hide");
}
});
}
}
innerToggle.children[0].innerText = labelForToggleButton(sectionIsCollapsed);
}

function collapseDocs(toggle, mode) {
Expand Down Expand Up @@ -1102,71 +1021,26 @@ function hideThemeButtonState() {
referenceNode.parentNode.insertBefore(newNode, referenceNode.nextSibling);
}

function createSimpleToggle(sectionIsCollapsed) {
var toggle = document.createElement("a");
toggle.href = "javascript:void(0)";
toggle.className = "collapse-toggle";
toggle.innerHTML = "[<span class=\"inner\">" + labelForToggleButton(sectionIsCollapsed) +
"</span>]";
return toggle;
}

function createToggle(toggle, otherMessage, fontSize, extraClass, show) {
var span = document.createElement("span");
span.className = "toggle-label";
if (show) {
span.style.display = "none";
}
if (!otherMessage) {
span.innerHTML = "&nbsp;Expand&nbsp;description";
} else {
span.innerHTML = otherMessage;
}

if (fontSize) {
span.style.fontSize = fontSize;
}

var mainToggle = toggle.cloneNode(true);
mainToggle.appendChild(span);

var wrapper = document.createElement("div");
wrapper.className = "toggle-wrapper";
if (!show) {
addClass(wrapper, "collapsed");
var inner = mainToggle.getElementsByClassName("inner");
if (inner && inner.length > 0) {
inner[0].innerHTML = "+";
}
}
if (extraClass) {
addClass(wrapper, extraClass);
}
wrapper.appendChild(mainToggle);
return wrapper;
}

(function() {
var toggles = document.getElementById(toggleAllDocsId);
if (toggles) {
toggles.onclick = toggleAllDocs;
}

var toggle = createSimpleToggle(false);
var hideMethodDocs = getSettingValue("auto-hide-method-docs") === "true";
var hideImplementors = getSettingValue("auto-collapse-implementors") !== "false";
var hideLargeItemContents = getSettingValue("auto-hide-large-items") !== "false";

var impl_list = document.getElementById("trait-implementations-list");
if (impl_list !== null) {
onEachLazy(impl_list.getElementsByClassName("collapse-toggle"), function(e) {
onEachLazy(impl_list.getElementsByClassName("rustdoc-toggle"), function(e) {
collapseNonInherent(e);
});
}

var blanket_list = document.getElementById("blanket-implementations-list");
if (blanket_list !== null) {
onEachLazy(blanket_list.getElementsByClassName("collapse-toggle"), function(e) {
onEachLazy(blanket_list.getElementsByClassName("rustdoc-toggle"), function(e) {
collapseNonInherent(e);
});
}
Expand Down Expand Up @@ -1205,66 +1079,6 @@ function hideThemeButtonState() {
}
}

function buildToggleWrapper(e) {
if (hasClass(e, "autohide")) {
var wrap = e.previousElementSibling;
if (wrap && hasClass(wrap, "toggle-wrapper")) {
var inner_toggle = wrap.childNodes[0];
var extra = e.childNodes[0].tagName === "H3";

e.style.display = "none";
addClass(wrap, "collapsed");
onEachLazy(inner_toggle.getElementsByClassName("inner"), function(e) {
e.innerHTML = labelForToggleButton(true);
});
onEachLazy(inner_toggle.getElementsByClassName("toggle-label"), function(e) {
e.style.display = "inline-block";
if (extra === true) {
e.innerHTML = " Show " + e.childNodes[0].innerHTML;
}
});
}
}
if (e.parentNode.id === "main") {
var otherMessage = "";
var fontSize;
var extraClass;

if (hasClass(e, "type-decl")) {
// We do something special for these
return;
} else if (hasClass(e, "non-exhaustive")) {
otherMessage = "&nbsp;This&nbsp;";
if (hasClass(e, "non-exhaustive-struct")) {
otherMessage += "struct";
} else if (hasClass(e, "non-exhaustive-enum")) {
otherMessage += "enum";
} else if (hasClass(e, "non-exhaustive-variant")) {
otherMessage += "enum variant";
} else if (hasClass(e, "non-exhaustive-type")) {
otherMessage += "type";
}
otherMessage += "&nbsp;is&nbsp;marked&nbsp;as&nbsp;non-exhaustive";
} else if (hasClass(e.childNodes[0], "impl-items")) {
extraClass = "marg-left";
}

e.parentNode.insertBefore(
createToggle(
toggle,
otherMessage,
fontSize,
extraClass,
true),
e);
if (hasClass(e, "non-exhaustive") === true) {
collapseDocs(e.previousSibling.childNodes[0], "toggle");
}
}
}

onEachLazy(document.getElementsByClassName("docblock"), buildToggleWrapper);

var pageId = getPageId();
if (pageId !== null) {
expandSection(pageId);
Expand Down
12 changes: 12 additions & 0 deletions src/librustdoc/html/static/rustdoc.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1790,6 +1790,18 @@ details.rustdoc-toggle > summary::before {
cursor: pointer;
}

details.rustdoc-toggle.top-doc > summary,
details.rustdoc-toggle.top-doc > summary::before,
details.rustdoc-toggle.non-exhaustive > summary,
details.rustdoc-toggle.non-exhaustive > summary::before {
font-family: 'Fira Sans';
font-size: 16px;
}

details.non-exhaustive {
margin-bottom: 8px;
}

details.rustdoc-toggle > summary.hideme::before {
position: relative;
}
Expand Down
Loading