nordic-dev.net/rust
nordic-dev.net/rust
2
0
Fork 0
mirror of https://github.com/rust-lang/rust.git synced 2024-11-27 09:14:20 +00:00
Code Issues Packages Projects Releases Wiki Activity

Rollup merge of #103060 - notriddle:notridddle/help-page, r=GuillaumeGomez

Browse Source 
rustdoc: make the help button a link to a page

This allows you to open the help section in a new browser tab, which is a pretty reasonable thing to want for a documentation page.

Preview: http://notriddle.com/notriddle-rustdoc-demos/help-page/std/index.html
This commit is contained in:
Matthias Krüger 2022-10-16 17:51:31 +02:00 committed by GitHub
commit 0bd24c5dc5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 172 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
src/librustdoc/html/markdown.rs
View File

@ -1433,6 +1433,7 @@ static DEFAULT_ID_MAP: Lazy<FxHashMap<Cow<'static, str>, usize>> = Lazy::new(||
fn init_id_map() -> FxHashMap<Cow<'static, str>, usize> {
let mut map = FxHashMap::default();
// This is the list of IDs used in Javascript.
map.insert("help".into(), 1);
map.insert("settings".into(), 1);
map.insert("not-displayed".into(), 1);
map.insert("alternative-display".into(), 1);

34
src/librustdoc/html/render/context.rs
View File

@ -581,6 +581,7 @@ impl<'tcx> FormatRenderer<'tcx> for Context<'tcx> {
let crate_name = self.tcx().crate_name(LOCAL_CRATE);
let final_file = self.dst.join(crate_name.as_str()).join("all.html");
let settings_file = self.dst.join("settings.html");
let help_file = self.dst.join("help.html");
let scrape_examples_help_file = self.dst.join("scrape-examples-help.html");
let mut root_path = self.dst.to_str().expect("invalid path").to_owned();
@ -657,6 +658,39 @@ impl<'tcx> FormatRenderer<'tcx> for Context<'tcx> {
);
shared.fs.write(settings_file, v)?;
// Generating help page.
page.title = "Rustdoc help";
page.description = "Documentation for Rustdoc";
page.root_path = "./";
let sidebar = "<h2 class=\"location\">Help</h2><div class=\"sidebar-elems\"></div>";
let v = layout::render(
&shared.layout,
&page,
sidebar,
|buf: &mut Buffer| {
write!(
buf,
"<div class=\"main-heading\">\
<h1 class=\"fqn\">Rustdoc help</h1>\
<span class=\"out-of-band\">\
<a id=\"back\" href=\"javascript:void(0)\" onclick=\"history.back();\">\
Back\
</a>\
</span>\
</div>\
<noscript>\
<section>\
<p>You need to enable Javascript to use keyboard commands or search.</p>\
<p>For more information, browse the <a href=\"https://doc.rust-lang.org/rustdoc/\">rustdoc handbook</a>.</p>\
</section>\
</noscript>",
)
},
&shared.style_files,
);
shared.fs.write(help_file, v)?;
if shared.layout.scrape_examples_extension {
page.title = "About scraped examples";
page.description = "How the scraped examples feature works in Rustdoc";

21
src/librustdoc/html/static/css/rustdoc.css
View File

@ -199,7 +199,7 @@ h1, h2, h3, h4, h5, h6,
.out-of-band,
span.since,
a.srclink,
#help-button > button,
#help-button > a,
details.rustdoc-toggle.top-doc > summary,
details.rustdoc-toggle.non-exhaustive > summary,
.scraped-example-title,
@ -974,32 +974,33 @@ so that we can apply CSS-filters to change the arrow color in themes */
color: var(--main-color);
}
#help-button .popover {
/* use larger max-width for help popover, but not for help.html */
#help.popover {
max-width: 600px;
}
#help-button .popover::before {
#help.popover::before {
right: 48px;
}
#help-button dt {
#help dt {
float: left;
clear: left;
display: block;
margin-right: 0.5rem;
}
#help-button span.top, #help-button span.bottom {
#help span.top, #help span.bottom {
text-align: center;
display: block;
font-size: 1.125rem;
}
#help-button span.top {
#help span.top {
margin: 10px 0;
border-bottom: 1px solid var(--border-color);
padding-bottom: 4px;
margin-bottom: 6px;
}
#help-button span.bottom {
#help span.bottom {
clear: both;
border-top: 1px solid var(--border-color);
}
@ -1433,7 +1434,7 @@ h3.variant {
outline: none;
}
#settings-menu > a, #help-button > button, #copy-path {
#settings-menu > a, #help-button > a, #copy-path {
padding: 5px;
width: 33px;
border: 1px solid var(--border-color);
@ -1442,7 +1443,7 @@ h3.variant {
line-height: 1.5;
}
#settings-menu > a, #help-button > button {
#settings-menu > a, #help-button > a {
padding: 5px;
height: 100%;
display: block;
@ -1490,7 +1491,7 @@ input:checked + .slider {
background-color: var(--settings-input-color);
}
#help-button > button {
#help-button > a {
text-align: center;
/* Rare exception to specifying font sizes in rem. Since this is acting
as an icon, it's okay to specify their sizes in pixels. */

4
src/librustdoc/html/static/css/themes/ayu.css
View File

@ -248,7 +248,7 @@ kbd {
box-shadow: inset 0 -1px 0 #5c6773;
}
#settings-menu > a, #help-button > button {
#settings-menu > a, #help-button > a {
color: #fff;
}
@ -257,7 +257,7 @@ kbd {
}
#settings-menu > a:hover, #settings-menu > a:focus,
#help-button > button:hover, #help-button > button:focus {
#help-button > a:hover, #help-button > a:focus {
border-color: #e0e0e0;
}

4
src/librustdoc/html/static/css/themes/dark.css
View File

@ -153,12 +153,12 @@ kbd {
box-shadow: inset 0 -1px 0 #c6cbd1;
}
#settings-menu > a, #help-button > button {
#settings-menu > a, #help-button > a {
color: #000;
}
#settings-menu > a:hover, #settings-menu > a:focus,
#help-button > button:hover, #help-button > button:focus {
#help-button > a:hover, #help-button > a:focus {
border-color: #ffb900;
}

6
src/librustdoc/html/static/css/themes/light.css
View File

@ -147,8 +147,12 @@ kbd {
box-shadow: inset 0 -1px 0 #c6cbd1;
}
#settings-menu > a, #help-button > a {
color: #000;
}
#settings-menu > a:hover, #settings-menu > a:focus,
#help-button > button:hover, #help-button > button:focus {
#help-button > a:hover, #help-button > a:focus {
border-color: #717171;
}

43
src/librustdoc/html/static/js/main.js
View File

@ -192,6 +192,8 @@ function loadCss(cssFileName) {
}
(function() {
const isHelpPage = window.location.pathname.endsWith("/help.html");
function loadScript(url) {
const script = document.createElement("script");
script.src = url;
@ -199,6 +201,9 @@ function loadCss(cssFileName) {
}
getSettingsButton().onclick = event => {
if (event.ctrlKey || event.altKey || event.metaKey) {
return;
}
addClass(getSettingsButton(), "rotate");
event.preventDefault();
// Sending request for the CSS and the JS files at the same time so it will
@ -873,7 +878,10 @@ function loadCss(cssFileName) {
rustdoc_version.appendChild(rustdoc_version_code);
const container = document.createElement("div");
if (!isHelpPage) {
container.className = "popover";
}
container.id = "help";
container.style.display = "none";
const side_by_side = document.createElement("div");
@ -885,6 +893,12 @@ function loadCss(cssFileName) {
container.appendChild(side_by_side);
container.appendChild(rustdoc_version);
if (isHelpPage) {
const help_section = document.createElement("section");
help_section.appendChild(container);
document.getElementById("main-content").appendChild(help_section);
container.style.display = "block";
} else {
const help_button = getHelpButton();
help_button.appendChild(container);
@ -894,6 +908,7 @@ function loadCss(cssFileName) {
};
help_button.onblur = helpBlurHandler;
help_button.children[0].onblur = helpBlurHandler;
}
return container;
}
@ -934,11 +949,34 @@ function loadCss(cssFileName) {
}
}
document.querySelector(`#${HELP_BUTTON_ID} > button`).addEventListener("click", event => {
if (isHelpPage) {
showHelp();
document.querySelector(`#${HELP_BUTTON_ID} > a`).addEventListener("click", event => {
// Already on the help page, make help button a no-op.
const target = event.target;
if (target.tagName !== "BUTTON" || target.parentElement.id !== HELP_BUTTON_ID) {
if (target.tagName !== "A" ||
target.parentElement.id !== HELP_BUTTON_ID ||
event.ctrlKey ||
event.altKey ||
event.metaKey) {
return;
}
event.preventDefault();
});
} else {
document.querySelector(`#${HELP_BUTTON_ID} > a`).addEventListener("click", event => {
// By default, have help button open docs in a popover.
// If user clicks with a moderator, though, use default browser behavior,
// probably opening in a new window or tab.
const target = event.target;
if (target.tagName !== "A" ||
target.parentElement.id !== HELP_BUTTON_ID ||
event.ctrlKey ||
event.altKey ||
event.metaKey) {
return;
}
event.preventDefault();
const menu = getHelpMenu(true);
const shouldShowHelp = menu.style.display === "none";
if (shouldShowHelp) {
@ -947,6 +985,7 @@ function loadCss(cssFileName) {
window.hidePopoverMenus();
}
});
}
setMobileTopbar();
addSidebarItems();

2
src/librustdoc/html/templates/page.html
View File

@ -122,7 +122,7 @@
placeholder="Click or press ‘S’ to search, ‘?’ for more options…" {# -#}
type="search"> {#- -#}
<div id="help-button" title="help" tabindex="-1"> {#- -#}
<button type="button">?</button> {#- -#}
<a href="{{page.root_path|safe}}help.html">?</a> {#- -#}
</div> {#- -#}
<div id="settings-menu" tabindex="-1"> {#- -#}
<a href="{{page.root_path|safe}}settings.html" title="settings"> {#- -#}

24
src/test/rustdoc-gui/help-page.goml Normal file
View File

@ -0,0 +1,24 @@
// This test ensures that opening the help page in its own tab works.
goto: "file://" + |DOC_PATH| + "/help.html"
size: (1000, 1000) // Try desktop size first.
wait-for: "#help"
assert-css: ("#help", {"display": "block"})
click: "#help-button > a"
assert-css: ("#help", {"display": "block"})
compare-elements-property: (".sub-container", "#help", ["offsetWidth"])
compare-elements-position: (".sub-container", "#help", ("x"))
size: (500, 1000) // Try mobile next.
assert-css: ("#help", {"display": "block"})
compare-elements-property: (".sub-container", "#help", ["offsetWidth"])
compare-elements-position: (".sub-container", "#help", ("x"))
// This test ensures that opening the help popover without switching pages works.
goto: "file://" + |DOC_PATH| + "/test_docs/index.html"
size: (1000, 1000) // Only supported on desktop.
assert-false: "#help"
click: "#help-button > a"
assert-css: ("#help", {"display": "block"})
click: "#help-button > a"
assert-css: ("#help", {"display": "none"})
compare-elements-property-false: (".sub-container", "#help", ["offsetWidth"])
compare-elements-position-false: (".sub-container", "#help", ("x"))

42
src/test/rustdoc-gui/search-form-elements.goml
View File

@ -33,7 +33,7 @@ assert-css: (
{"border-color": "rgb(197, 197, 197)"},
)
assert-css: (
"#help-button > button",
"#help-button > a",
{
"color": "rgb(255, 255, 255)",
"border-color": "rgb(92, 103, 115)",
@ -47,13 +47,21 @@ assert-css: (
)
// Only "border-color" should change.
assert-css: (
"#help-button:hover > button",
"#help-button:hover > a",
{
"color": "rgb(255, 255, 255)",
"border-color": "rgb(224, 224, 224)",
"background-color": "rgb(20, 25, 32)",
},
)
// Link color inside
click: "#help-button"
assert-css: (
"#help a",
{
"color": "rgb(57, 175, 215)",
},
)
assert-css: (
"#settings-menu",
@ -62,7 +70,6 @@ assert-css: (
assert-css: (
"#settings-menu > a",
{
"color": "rgb(255, 255, 255)",
"border-color": "rgb(92, 103, 115)",
"background-color": "rgb(20, 25, 32)",
},
@ -76,7 +83,6 @@ assert-css: (
assert-css: (
"#settings-menu:hover > a",
{
"color": "rgb(255, 255, 255)",
"border-color": "rgb(224, 224, 224)",
"background-color": "rgb(20, 25, 32)",
},
@ -113,7 +119,7 @@ assert-css: (
{"border-color": "rgb(221, 221, 221)"},
)
assert-css: (
"#help-button > button",
"#help-button > a",
{
"color": "rgb(0, 0, 0)",
"border-color": "rgb(224, 224, 224)",
@ -127,13 +133,21 @@ assert-css: (
)
// Only "border-color" should change.
assert-css: (
"#help-button:hover > button",
"#help-button:hover > a",
{
"color": "rgb(0, 0, 0)",
"border-color": "rgb(255, 185, 0)",
"background-color": "rgb(240, 240, 240)",
},
)
// Link color inside
click: "#help-button"
assert-css: (
"#help a",
{
"color": "rgb(210, 153, 29)",
},
)
assert-css: (
"#settings-menu",
@ -142,7 +156,6 @@ assert-css: (
assert-css: (
"#settings-menu > a",
{
"color": "rgb(0, 0, 0)",
"border-color": "rgb(224, 224, 224)",
"background-color": "rgb(240, 240, 240)",
},
@ -193,7 +206,7 @@ assert-css: (
{"border-color": "rgb(0, 0, 0)"},
)
assert-css: (
"#help-button > button",
"#help-button > a",
{
"color": "rgb(0, 0, 0)",
"border-color": "rgb(224, 224, 224)",
@ -207,13 +220,21 @@ assert-css: (
)
// Only "border-color" should change.
assert-css: (
"#help-button:hover > button",
"#help-button:hover > a",
{
"color": "rgb(0, 0, 0)",
"border-color": "rgb(113, 113, 113)",
"background-color": "rgb(255, 255, 255)",
},
)
// Link color inside
click: "#help-button"
assert-css: (
"#help a",
{
"color": "rgb(56, 115, 173)",
},
)
assert-css: (
"#settings-menu",
@ -222,7 +243,6 @@ assert-css: (
assert-css: (
"#settings-menu > a",
{
"color": "rgb(56, 115, 173)",
"border-color": "rgb(224, 224, 224)",
"background-color": "rgb(255, 255, 255)",
},
@ -236,7 +256,7 @@ assert-css: (
assert-css: (
"#settings-menu:hover > a",
{
"color": "rgb(56, 115, 173)",
"color": "rgb(0, 0, 0)",
"border-color": "rgb(113, 113, 113)",
"background-color": "rgb(255, 255, 255)",
},