Add "danger" and "note" CSS classes

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

@@ -254,7 +254,7 @@ characters:
 
 So, no need to manually enter those Unicode characters!
 
-### Adding a warning block
+### Adding a note/warning/danger block
 
 If you want to make a warning or similar note stand out in the documentation,
 you can wrap it like this:
@@ -267,6 +267,11 @@ you can wrap it like this:
 /// more documentation
 ```
 
+There are three levels available:
+ * note
+ * warning
+ * danger
+
 [`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,18 @@ ul ul, ol ul, ul ol, ol ol {
 	margin-bottom: .625em;
 }
 
-p, .docblock > .warning {
+p, .docblock > .note, .docblock > .warning, .docblock > .danger {
 	/* 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, .docblock > .warning:last-child {
+p:last-child,
+.docblock > .note:last-child,
+.docblock > .warning:last-child,
+.docblock > .danger:last-child {
 	margin: 0;
 }
 
@@ -1124,25 +1127,45 @@ pre.rust .doccomment {
 	font-size: 1.25rem;
 }
 
-/* This class only exists for users who want to draw attention to a particular element in their
+/* These classes only exist 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);
+.content .docblock .note,
+.content .docblock .warning,
+.content .docblock .danger {
 	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 .docblock .note::before,
+.content .docblock .warning::before,
+.content .docblock .danger::before {
 	content: "ⓘ";
 	position: absolute;
 	left: -25px;
 	top: 5px;
 	font-weight: bold;
 	font-size: 1.25rem;
 }
+.content .docblock .note {
+	border-left: 2px solid var(--note-border-color);
+}
+.content .docblock .warning {
+	border-left: 2px solid var(--warning-border-color);
+}
+.content .docblock .danger {
+	border-left: 2px solid var(--danger-border-color);
+}
+.content .docblock .note::before {
+	color: var(--note-border-color);
+}
+.content .docblock .warning::before {
+	color: var(--warning-border-color);
+}
+.content .docblock .danger::before {
+	color: var(--danger-border-color);
+}
 
 a.test-arrow {
 	visibility: hidden;

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

@@ -31,7 +31,9 @@ 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);
+	--note-border-color: #00abff;
+	--warning-border-color: #ff8e00;
+	--danger-border-color: #ff2323;
 	--type-link-color: #ffa0a5;
 	--trait-link-color: #39afd7;
 	--assoc-item-link-color: #39afd7;

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

@@ -26,7 +26,9 @@
 	--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);
+	--note-border-color: #0087ff;
+	--warning-border-color: #ff8e00;
+	--danger-border-color: #d22525;
 	--type-link-color: #2dbfb8;
 	--trait-link-color: #b78cf2;
 	--assoc-item-link-color: #d2991d;

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

@@ -26,7 +26,9 @@
 	--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);
+	--note-border-color: #0087ff;
+	--warning-border-color: #ff8e00;
+	--danger-border-color: #d22525;
 	--type-link-color: #ad378a;
 	--trait-link-color: #6e4fc9;
 	--assoc-item-link-color: #3873ad;

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

@@ -68,8 +68,12 @@ impl Foo {
 
     /// hello
     ///
+    /// <div id="doc-note" class="note">this is a note</div>
+    ///
     /// <div id="doc-warning-1" class="warning">this is a warning</div>
     ///
+    /// <div id="doc-danger" class="danger">this is a danger</div>
+    ///
     /// done
     pub fn warning1() {}
 

tests/rustdoc-gui/warning-block.goml

@@ -4,42 +4,57 @@ show-text: true
 
 define-function: (
     "check-warning",
-    (theme, color, border_color, background_color),
+    (theme, color, note_color, warning_color, danger_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-note", {
+            "margin-bottom": "12px",
+            "color": |color|,
+            "border-left": "2px solid " + |note_color|,
+            "background-color": "transparent",
+        })
         assert-css: ("#doc-warning-1", {
             "margin-bottom": "12px",
             "color": |color|,
-            "border-left": "2px solid " + |border_color|,
-            "background-color": |background_color|,
+            "border-left": "2px solid " + |warning_color|,
+            "background-color": "transparent",
+        })
+        assert-css: ("#doc-danger", {
+            "margin-bottom": "12px",
+            "color": |color|,
+            "border-left": "2px solid " + |danger_color|,
+            "background-color": "transparent",
         })
         assert-css: ("#doc-warning-2", {
             "margin-bottom": "0px",
             "color": |color|,
-            "border-left": "2px solid " + |border_color|,
-            "background-color": |background_color|,
+            "border-left": "2px solid " + |warning_color|,
+            "background-color": "transparent",
         })
     },
 )
 
 call-function: ("check-warning", {
     "theme": "ayu",
-    "color": "rgb(197, 197, 197)",
-    "border_color": "rgb(255, 142, 0)",
-    "background_color": "rgba(0, 0, 0, 0)",
+    "color": "#c5c5c5",
+    "note_color": "#00abff",
+    "warning_color": "#ff8e00",
+    "danger_color": "#ff2323",
 })
 call-function: ("check-warning", {
     "theme": "dark",
-    "color": "rgb(221, 221, 221)",
-    "border_color": "rgb(255, 142, 0)",
-    "background_color": "rgba(0, 0, 0, 0)",
+    "color": "#ddd",
+    "note_color": "#0087ff",
+    "warning_color": "#ff8e00",
+    "danger_color": "#d22525",
 })
 call-function: ("check-warning", {
     "theme": "light",
-    "color": "rgb(0, 0, 0)",
-    "border_color": "rgb(255, 142, 0)",
-    "background_color": "rgba(0, 0, 0, 0)",
+    "color": "black",
+    "note_color": "#0087ff",
+    "warning_color": "#ff8e00",
+    "danger_color": "#d22525",
 })