Auto merge of #106561 - GuillaumeGomez:warning-block, r=rustdoc

Add warning block support in rustdoc

Fixes #79710.

You can test it [here](https://rustdoc.crud.net/imperio/warning-block/foo/struct.Foo.html). It currently looks like this:

![image](https://user-images.githubusercontent.com/3050060/211413494-e1cf04e4-c081-4a9d-97db-27329405cfa7.png)

So a few things to note:

 * Since it's a new add and it's changing the UI, we'll need to go through an FCP.
 * Does the UI looks good?
 * Is the way picked to add a warning block ok for everyone? The discussion on the issue seemed to be in favour of this solution but it doesn't hurt to double-check.

cc `@rust-lang/rustdoc`

Author: bors

src/doc/rustdoc/src/how-to-write-documentation.md

@@ -254,6 +254,19 @@ characters:
 
 So, no need to manually enter those Unicode characters!
 
+### Adding a warning block
+
+If you want to make a warning or similar note stand out in the documentation,
+you can wrap it like this:
+
+```md
+/// documentation
+///
+/// <div class="warning">A big warning!</div>
+///
+/// more documentation
+```
+
 [`backtrace`]: https://docs.rs/backtrace/0.3.50/backtrace/
 [commonmark markdown specification]: https://commonmark.org/
 [commonmark quick reference]: https://commonmark.org/help/

src/librustdoc/html/static/css/rustdoc.css

@@ -270,15 +270,15 @@ ul ul, ol ul, ul ol, ol ol {
 	margin-bottom: .625em;
 }
 
-p {
+p, .docblock > .warning {
 	/* Paragraph spacing at least 1.5 times line spacing per Web Content Accessibility Guidelines.
 	   Line-height is 1.5rem, so line spacing is .5rem; .75em is 1.5 times that.
 	   https://www.w3.org/WAI/WCAG21/Understanding/visual-presentation.html */
 	margin: 0 0 .75em 0;
 }
 /* For the last child of a div, the margin will be taken care of
 	by the margin-top of the next item. */
-p:last-child {
+p:last-child, .docblock > .warning:last-child {
 	margin: 0;
 }
 
@@ -1096,7 +1096,7 @@ pre.rust .doccomment {
 }
 
 .example-wrap.ignore .tooltip {
-	color:  var(--codeblock-ignore-color);
+	color: var(--codeblock-ignore-color);
 }
 
 .example-wrap.compile_fail:hover .tooltip,
@@ -1124,6 +1124,26 @@ pre.rust .doccomment {
 	font-size: 1.25rem;
 }
 
+/* This class only exists for users who want to draw attention to a particular element in their
+documentation. */
+.content .docblock .warning {
+	border-left: 2px solid var(--warning-border-color);
+	padding: 14px;
+	position: relative;
+	/* The "!important" part is required because the rule is otherwise overruled in this CSS
+	selector: ".docblock > :not(.more-examples-toggle):not(.example-wrap)" */
+	overflow-x: visible !important;
+}
+.content .docblock .warning::before {
+	color: var(--warning-border-color);
+	content: "ⓘ";
+	position: absolute;
+	left: -25px;
+	top: 5px;
+	font-weight: bold;
+	font-size: 1.25rem;
+}
+
 a.test-arrow {
 	visibility: hidden;
 	position: absolute;

src/librustdoc/html/static/css/themes/ayu.css

@@ -31,6 +31,7 @@ Original by Dempfi (https://github.com/dempfi/ayu)
 	--codeblock-error-color: rgba(255, 0, 0, .5);
 	--codeblock-ignore-hover-color: rgb(255, 142, 0);
 	--codeblock-ignore-color: rgba(255, 142, 0, .6);
+	--warning-border-color: rgb(255, 142, 0);
 	--type-link-color: #ffa0a5;
 	--trait-link-color: #39afd7;
 	--assoc-item-link-color: #39afd7;

src/librustdoc/html/static/css/themes/dark.css

@@ -26,6 +26,7 @@
 	--codeblock-error-color: rgba(255, 0, 0, .5);
 	--codeblock-ignore-hover-color: rgb(255, 142, 0);
 	--codeblock-ignore-color: rgba(255, 142, 0, .6);
+	--warning-border-color: rgb(255, 142, 0);
 	--type-link-color: #2dbfb8;
 	--trait-link-color: #b78cf2;
 	--assoc-item-link-color: #d2991d;

src/librustdoc/html/static/css/themes/light.css

@@ -26,6 +26,7 @@
 	--codeblock-error-color: rgba(255, 0, 0, .5);
 	--codeblock-ignore-hover-color: rgb(255, 142, 0);
 	--codeblock-ignore-color: rgba(255, 142, 0, .6);
+	--warning-border-color: rgb(255, 142, 0);
 	--type-link-color: #ad378a;
 	--trait-link-color: #6e4fc9;
 	--assoc-item-link-color: #3873ad;

tests/rustdoc-gui/src/test_docs/lib.rs

@@ -65,6 +65,18 @@ impl Foo {
     pub fn must_use(&self) -> bool {
         true
     }
+
+    /// hello
+    ///
+    /// <div id="doc-warning-1" class="warning">this is a warning</div>
+    ///
+    /// done
+    pub fn warning1() {}
+
+    /// Checking there is no bottom margin if "warning" is the last element.
+    ///
+    /// <div id="doc-warning-2" class="warning">this is a warning</div>
+    pub fn warning2() {}
 }
 
 impl AsRef<str> for Foo {

tests/rustdoc-gui/warning-block.goml

@@ -0,0 +1,45 @@
+// Test to check that the "warning blocks" are displayed as expected.
+go-to: "file://" + |DOC_PATH| + "/test_docs/struct.Foo.html"
+show-text: true
+
+define-function: (
+    "check-warning",
+    (theme, color, border_color, background_color),
+    block {
+        set-local-storage: {"rustdoc-theme": |theme|, "rustdoc-use-system-theme": "false"}
+        reload:
+
+        // The IDs are added directly into the DOM to make writing this test easier.
+        assert-css: ("#doc-warning-1", {
+            "margin-bottom": "12px",
+            "color": |color|,
+            "border-left": "2px solid " + |border_color|,
+            "background-color": |background_color|,
+        })
+        assert-css: ("#doc-warning-2", {
+            "margin-bottom": "0px",
+            "color": |color|,
+            "border-left": "2px solid " + |border_color|,
+            "background-color": |background_color|,
+        })
+    },
+)
+
+call-function: ("check-warning", {
+    "theme": "ayu",
+    "color": "rgb(197, 197, 197)",
+    "border_color": "rgb(255, 142, 0)",
+    "background_color": "rgba(0, 0, 0, 0)",
+})
+call-function: ("check-warning", {
+    "theme": "dark",
+    "color": "rgb(221, 221, 221)",
+    "border_color": "rgb(255, 142, 0)",
+    "background_color": "rgba(0, 0, 0, 0)",
+})
+call-function: ("check-warning", {
+    "theme": "light",
+    "color": "rgb(0, 0, 0)",
+    "border_color": "rgb(255, 142, 0)",
+    "background_color": "rgba(0, 0, 0, 0)",
+})