rustdoc: make the help button a link to a page

notriddle · notriddle · commit ae4ad9adb68c · 2022-10-15T11:38:42.000-07:00
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.
diff --git a/src/librustdoc/html/markdown.rs b/src/librustdoc/html/markdown.rs
@@ -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);
diff --git a/src/librustdoc/html/render/context.rs b/src/librustdoc/html/render/context.rs
@@ -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";
diff --git a/src/librustdoc/html/static/css/rustdoc.css b/src/librustdoc/html/static/css/rustdoc.css
@@ -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. */
diff --git a/src/librustdoc/html/static/css/themes/ayu.css b/src/librustdoc/html/static/css/themes/ayu.css
@@ -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;
 }
 
diff --git a/src/librustdoc/html/static/css/themes/dark.css b/src/librustdoc/html/static/css/themes/dark.css
@@ -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;
 }
 
diff --git a/src/librustdoc/html/static/css/themes/light.css b/src/librustdoc/html/static/css/themes/light.css
@@ -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;
 }
 
diff --git a/src/librustdoc/html/static/js/main.js b/src/librustdoc/html/static/js/main.js
@@ -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;
@@ -873,7 +875,10 @@ function loadCss(cssFileName) {
         rustdoc_version.appendChild(rustdoc_version_code);
 
         const container = document.createElement("div");
-        container.className = "popover";
+        if (!isHelpPage) {
+            container.className = "popover";
+        }
+        container.id = "help";
         container.style.display = "none";
 
         const side_by_side = document.createElement("div");
@@ -885,15 +890,22 @@ function loadCss(cssFileName) {
         container.appendChild(side_by_side);
         container.appendChild(rustdoc_version);
 
-        const help_button = getHelpButton();
-        help_button.appendChild(container);
-
-        container.onblur = helpBlurHandler;
-        container.onclick = event => {
-            event.preventDefault();
-        };
-        help_button.onblur = helpBlurHandler;
-        help_button.children[0].onblur = helpBlurHandler;
+        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);
+
+            container.onblur = helpBlurHandler;
+            container.onclick = event => {
+                event.preventDefault();
+            };
+            help_button.onblur = helpBlurHandler;
+            help_button.children[0].onblur = helpBlurHandler;
+        }
 
         return container;
     }
@@ -934,19 +946,24 @@ function loadCss(cssFileName) {
         }
     }
 
-    document.querySelector(`#${HELP_BUTTON_ID} > button`).addEventListener("click", event => {
-        const target = event.target;
-        if (target.tagName !== "BUTTON" || target.parentElement.id !== HELP_BUTTON_ID) {
-            return;
-        }
-        const menu = getHelpMenu(true);
-        const shouldShowHelp = menu.style.display === "none";
-        if (shouldShowHelp) {
-            showHelp();
-        } else {
-            window.hidePopoverMenus();
-        }
-    });
+    if (isHelpPage) {
+        showHelp();
+    } else {
+        document.querySelector(`#${HELP_BUTTON_ID} > a`).addEventListener("click", event => {
+            const target = event.target;
+            if (target.tagName !== "A" || target.parentElement.id !== HELP_BUTTON_ID) {
+                return;
+            }
+            event.preventDefault();
+            const menu = getHelpMenu(true);
+            const shouldShowHelp = menu.style.display === "none";
+            if (shouldShowHelp) {
+                showHelp();
+            } else {
+                window.hidePopoverMenus();
+            }
+        });
+    }
 
     setMobileTopbar();
     addSidebarItems();
diff --git a/src/librustdoc/html/templates/page.html b/src/librustdoc/html/templates/page.html
@@ -122,7 +122,7 @@ <h2 class="location"></h2> {#- -#}
                                 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"> {#- -#}
diff --git a/src/test/rustdoc-gui/help-page.goml b/src/test/rustdoc-gui/help-page.goml
@@ -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"))
diff --git a/src/test/rustdoc-gui/search-form-elements.goml b/src/test/rustdoc-gui/search-form-elements.goml
@@ -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,7 +47,7 @@ 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)",
@@ -113,7 +113,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,7 +127,7 @@ 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)",
@@ -193,7 +193,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,7 +207,7 @@ 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)",
@@ -222,7 +222,7 @@ assert-css: (
 assert-css: (
     "#settings-menu > a",
     {
-        "color": "rgb(56, 115, 173)",
+        "color": "rgb(0, 0, 0)",
         "border-color": "rgb(224, 224, 224)",
         "background-color": "rgb(255, 255, 255)",
     },
@@ -236,7 +236,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)",
     },

Original file line number	Diff line number	Diff line change
`@@ -248,7 +248,7 @@ kbd {`
`248`	`248`	`box-shadow: inset 0 -1px 0 #5c6773;`
`249`	`249`	`}`
`250`	`250`
`251`		`-#settings-menu > a, #help-button > button {`
	`251`	`+#settings-menu > a, #help-button > a {`
`252`	`252`	`color: #fff;`
`253`	`253`	`}`
`254`	`254`
`@@ -257,7 +257,7 @@ kbd {`
`257`	`257`	`}`
`258`	`258`
`259`	`259`	`#settings-menu > a:hover, #settings-menu > a:focus,`
`260`		`-#help-button > button:hover, #help-button > button:focus {`
	`260`	`+#help-button > a:hover, #help-button > a:focus {`
`261`	`261`	`border-color: #e0e0e0;`
`262`	`262`	`}`
`263`	`263`
Original file line number	Diff line number	Diff line change
`@@ -153,12 +153,12 @@ kbd {`
`153`	`153`	`box-shadow: inset 0 -1px 0 #c6cbd1;`
`154`	`154`	`}`
`155`	`155`
`156`		`-#settings-menu > a, #help-button > button {`
	`156`	`+#settings-menu > a, #help-button > a {`
`157`	`157`	`color: #000;`
`158`	`158`	`}`
`159`	`159`
`160`	`160`	`#settings-menu > a:hover, #settings-menu > a:focus,`
`161`		`-#help-button > button:hover, #help-button > button:focus {`
	`161`	`+#help-button > a:hover, #help-button > a:focus {`
`162`	`162`	`border-color: #ffb900;`
`163`	`163`	`}`
`164`	`164`
Original file line number	Diff line number	Diff line change
`@@ -147,8 +147,12 @@ kbd {`
`147`	`147`	`box-shadow: inset 0 -1px 0 #c6cbd1;`
`148`	`148`	`}`
`149`	`149`
	`150`	`+#settings-menu > a, #help-button > a {`
	`151`	`+ color: #000;`
	`152`	`+}`
	`153`	`+`
`150`	`154`	`#settings-menu > a:hover, #settings-menu > a:focus,`
`151`		`-#help-button > button:hover, #help-button > button:focus {`
	`155`	`+#help-button > a:hover, #help-button > a:focus {`
`152`	`156`	`border-color: #717171;`
`153`	`157`	`}`
`154`	`158`
Original file line number	Diff line number	Diff line change
`@@ -33,7 +33,7 @@ assert-css: (`
`33`	`33`	`{"border-color": "rgb(197, 197, 197)"},`
`34`	`34`	`)`
`35`	`35`	`assert-css: (`
`36`		`- "#help-button > button",`
	`36`	`+ "#help-button > a",`
`37`	`37`	`{`
`38`	`38`	`"color": "rgb(255, 255, 255)",`
`39`	`39`	`"border-color": "rgb(92, 103, 115)",`
`@@ -47,7 +47,7 @@ assert-css: (`
`47`	`47`	`)`
`48`	`48`	`// Only "border-color" should change.`
`49`	`49`	`assert-css: (`
`50`		`- "#help-button:hover > button",`
	`50`	`+ "#help-button:hover > a",`
`51`	`51`	`{`
`52`	`52`	`"color": "rgb(255, 255, 255)",`
`53`	`53`	`"border-color": "rgb(224, 224, 224)",`
`@@ -113,7 +113,7 @@ assert-css: (`
`113`	`113`	`{"border-color": "rgb(221, 221, 221)"},`
`114`	`114`	`)`
`115`	`115`	`assert-css: (`
`116`		`- "#help-button > button",`
	`116`	`+ "#help-button > a",`
`117`	`117`	`{`
`118`	`118`	`"color": "rgb(0, 0, 0)",`
`119`	`119`	`"border-color": "rgb(224, 224, 224)",`
`@@ -127,7 +127,7 @@ assert-css: (`
`127`	`127`	`)`
`128`	`128`	`// Only "border-color" should change.`
`129`	`129`	`assert-css: (`
`130`		`- "#help-button:hover > button",`
	`130`	`+ "#help-button:hover > a",`
`131`	`131`	`{`
`132`	`132`	`"color": "rgb(0, 0, 0)",`
`133`	`133`	`"border-color": "rgb(255, 185, 0)",`
`@@ -193,7 +193,7 @@ assert-css: (`
`193`	`193`	`{"border-color": "rgb(0, 0, 0)"},`
`194`	`194`	`)`
`195`	`195`	`assert-css: (`
`196`		`- "#help-button > button",`
	`196`	`+ "#help-button > a",`
`197`	`197`	`{`
`198`	`198`	`"color": "rgb(0, 0, 0)",`
`199`	`199`	`"border-color": "rgb(224, 224, 224)",`
`@@ -207,7 +207,7 @@ assert-css: (`
`207`	`207`	`)`
`208`	`208`	`// Only "border-color" should change.`
`209`	`209`	`assert-css: (`
`210`		`- "#help-button:hover > button",`
	`210`	`+ "#help-button:hover > a",`
`211`	`211`	`{`
`212`	`212`	`"color": "rgb(0, 0, 0)",`
`213`	`213`	`"border-color": "rgb(113, 113, 113)",`
`@@ -222,7 +222,7 @@ assert-css: (`
`222`	`222`	`assert-css: (`
`223`	`223`	`"#settings-menu > a",`
`224`	`224`	`{`
`225`		`- "color": "rgb(56, 115, 173)",`
	`225`	`+ "color": "rgb(0, 0, 0)",`
`226`	`226`	`"border-color": "rgb(224, 224, 224)",`
`227`	`227`	`"background-color": "rgb(255, 255, 255)",`
`228`	`228`	`},`
`@@ -236,7 +236,7 @@ assert-css: (`
`236`	`236`	`assert-css: (`
`237`	`237`	`"#settings-menu:hover > a",`
`238`	`238`	`{`
`239`		`- "color": "rgb(56, 115, 173)",`
	`239`	`+ "color": "rgb(0, 0, 0)",`
`240`	`240`	`"border-color": "rgb(113, 113, 113)",`
`241`	`241`	`"background-color": "rgb(255, 255, 255)",`
`242`	`242`	`},`