From b400162246379426fb25d35c7be527ce39b9a2cd Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Thu, 24 Aug 2023 17:42:10 +0200 Subject: [PATCH 1/4] Add "danger" and "note" CSS classes --- src/librustdoc/html/static/css/rustdoc.css | 37 +++++++++++++++---- src/librustdoc/html/static/css/themes/ayu.css | 4 +- .../html/static/css/themes/dark.css | 4 +- .../html/static/css/themes/light.css | 4 +- 4 files changed, 39 insertions(+), 10 deletions(-) diff --git a/src/librustdoc/html/static/css/rustdoc.css b/src/librustdoc/html/static/css/rustdoc.css index da4da50106abb..c887ff9074980 100644 --- a/src/librustdoc/html/static/css/rustdoc.css +++ b/src/librustdoc/html/static/css/rustdoc.css @@ -270,7 +270,7 @@ 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 */ @@ -278,7 +278,10 @@ p, .docblock > .warning { } /* 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,18 +1127,20 @@ 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; @@ -1143,6 +1148,24 @@ documentation. */ 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; diff --git a/src/librustdoc/html/static/css/themes/ayu.css b/src/librustdoc/html/static/css/themes/ayu.css index c81a80eeca059..0c0ad0e8e5180 100644 --- a/src/librustdoc/html/static/css/themes/ayu.css +++ b/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; diff --git a/src/librustdoc/html/static/css/themes/dark.css b/src/librustdoc/html/static/css/themes/dark.css index 0f8b1dc24a651..d9faed6f83077 100644 --- a/src/librustdoc/html/static/css/themes/dark.css +++ b/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; diff --git a/src/librustdoc/html/static/css/themes/light.css b/src/librustdoc/html/static/css/themes/light.css index 39ea44a116544..2eca3a05b692d 100644 --- a/src/librustdoc/html/static/css/themes/light.css +++ b/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; From 250990f4d2bbb7a2e9b494086b876cf86cd1aacd Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Thu, 24 Aug 2023 17:42:31 +0200 Subject: [PATCH 2/4] Migrate GUI colors test to original CSS color format --- tests/rustdoc-gui/warning-block.goml | 21 +++++++++------------ 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/tests/rustdoc-gui/warning-block.goml b/tests/rustdoc-gui/warning-block.goml index 2a935bd1a9bb5..8832b65c4d8d6 100644 --- a/tests/rustdoc-gui/warning-block.goml +++ b/tests/rustdoc-gui/warning-block.goml @@ -4,7 +4,7 @@ show-text: true define-function: ( "check-warning", - (theme, color, border_color, background_color), + (theme, color, border_color), block { set-local-storage: {"rustdoc-theme": |theme|, "rustdoc-use-system-theme": "false"} reload: @@ -14,32 +14,29 @@ define-function: ( "margin-bottom": "12px", "color": |color|, "border-left": "2px solid " + |border_color|, - "background-color": |background_color|, + "background-color": "transparent", }) assert-css: ("#doc-warning-2", { "margin-bottom": "0px", "color": |color|, "border-left": "2px solid " + |border_color|, - "background-color": |background_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", + "border_color": "#ff8e00", }) 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", + "border_color": "#ff8e00", }) 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", + "border_color": "#ff8e00", }) From 4e401447ea8612411e79a2e622236be7bd99ea53 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Thu, 24 Aug 2023 17:48:13 +0200 Subject: [PATCH 3/4] Add tests for note and danger elements --- tests/rustdoc-gui/src/test_docs/lib.rs | 4 ++++ tests/rustdoc-gui/warning-block.goml | 30 ++++++++++++++++++++------ 2 files changed, 28 insertions(+), 6 deletions(-) diff --git a/tests/rustdoc-gui/src/test_docs/lib.rs b/tests/rustdoc-gui/src/test_docs/lib.rs index 38180aef762b4..e869049db8556 100644 --- a/tests/rustdoc-gui/src/test_docs/lib.rs +++ b/tests/rustdoc-gui/src/test_docs/lib.rs @@ -68,8 +68,12 @@ impl Foo { /// hello /// + ///
this is a note
+ /// ///
this is a warning
/// + ///
this is a danger
+ /// /// done pub fn warning1() {} diff --git a/tests/rustdoc-gui/warning-block.goml b/tests/rustdoc-gui/warning-block.goml index 8832b65c4d8d6..4af62b334a05e 100644 --- a/tests/rustdoc-gui/warning-block.goml +++ b/tests/rustdoc-gui/warning-block.goml @@ -4,22 +4,34 @@ show-text: true define-function: ( "check-warning", - (theme, color, border_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|, + "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|, + "border-left": "2px solid " + |warning_color|, "background-color": "transparent", }) }, @@ -28,15 +40,21 @@ define-function: ( call-function: ("check-warning", { "theme": "ayu", "color": "#c5c5c5", - "border_color": "#ff8e00", + "note_color": "#00abff", + "warning_color": "#ff8e00", + "danger_color": "#ff2323", }) call-function: ("check-warning", { "theme": "dark", "color": "#ddd", - "border_color": "#ff8e00", + "note_color": "#0087ff", + "warning_color": "#ff8e00", + "danger_color": "#d22525", }) call-function: ("check-warning", { "theme": "light", "color": "black", - "border_color": "#ff8e00", + "note_color": "#0087ff", + "warning_color": "#ff8e00", + "danger_color": "#d22525", }) From 8d75d2fccee15a65e849e751de441aa99dc91f85 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Thu, 24 Aug 2023 17:51:52 +0200 Subject: [PATCH 4/4] Add documentation for "note" and "danger" elements in docs --- src/doc/rustdoc/src/how-to-write-documentation.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/doc/rustdoc/src/how-to-write-documentation.md b/src/doc/rustdoc/src/how-to-write-documentation.md index acab1a93690c5..7d22e70fecd80 100644 --- a/src/doc/rustdoc/src/how-to-write-documentation.md +++ b/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/