From d51521e28044edcff0a1f7666629e5e7aea73727 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Sat, 7 Jan 2023 14:48:55 +0100 Subject: [PATCH 1/3] Add warning block support in rustdoc --- src/librustdoc/html/static/css/rustdoc.css | 26 ++++++++++++++++--- src/librustdoc/html/static/css/themes/ayu.css | 1 + .../html/static/css/themes/dark.css | 1 + .../html/static/css/themes/light.css | 1 + 4 files changed, 26 insertions(+), 3 deletions(-) diff --git a/src/librustdoc/html/static/css/rustdoc.css b/src/librustdoc/html/static/css/rustdoc.css index b1de8c1529e78..da4da50106abb 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 { +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 */ @@ -278,7 +278,7 @@ p { } /* 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; diff --git a/src/librustdoc/html/static/css/themes/ayu.css b/src/librustdoc/html/static/css/themes/ayu.css index d8dae51eb1bff..c81a80eeca059 100644 --- a/src/librustdoc/html/static/css/themes/ayu.css +++ b/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; diff --git a/src/librustdoc/html/static/css/themes/dark.css b/src/librustdoc/html/static/css/themes/dark.css index 2b302988734fa..0f8b1dc24a651 100644 --- a/src/librustdoc/html/static/css/themes/dark.css +++ b/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; diff --git a/src/librustdoc/html/static/css/themes/light.css b/src/librustdoc/html/static/css/themes/light.css index 56fd8cbef121c..39ea44a116544 100644 --- a/src/librustdoc/html/static/css/themes/light.css +++ b/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; From 57d2b84a57225717c6af8748574b4a847d62433c Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Sat, 7 Jan 2023 14:49:11 +0100 Subject: [PATCH 2/3] Add documentation for warning blocks in rustdoc book --- src/doc/rustdoc/src/how-to-write-documentation.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/doc/rustdoc/src/how-to-write-documentation.md b/src/doc/rustdoc/src/how-to-write-documentation.md index 1fa9f81447607..aaabaa6098f5c 100644 --- a/src/doc/rustdoc/src/how-to-write-documentation.md +++ b/src/doc/rustdoc/src/how-to-write-documentation.md @@ -254,6 +254,18 @@ characters: So, no need to manually enter those Unicode characters! +### Adding a warning block + +If you want to make a "warning" stand out in the documentation, you can wrap it like this: + +```md +/// documentation +/// +///
A big warning!
+/// +/// more documentation +``` + [`backtrace`]: https://docs.rs/backtrace/0.3.50/backtrace/ [commonmark markdown specification]: https://commonmark.org/ [commonmark quick reference]: https://commonmark.org/help/ From 1d42913058d4005655ea51b2d9dde707791c6541 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Sat, 7 Jan 2023 14:50:03 +0100 Subject: [PATCH 3/3] Add GUI test for warning blocks --- .../rustdoc/src/how-to-write-documentation.md | 3 +- tests/rustdoc-gui/src/test_docs/lib.rs | 12 +++++ tests/rustdoc-gui/warning-block.goml | 45 +++++++++++++++++++ 3 files changed, 59 insertions(+), 1 deletion(-) create mode 100644 tests/rustdoc-gui/warning-block.goml diff --git a/src/doc/rustdoc/src/how-to-write-documentation.md b/src/doc/rustdoc/src/how-to-write-documentation.md index aaabaa6098f5c..acab1a93690c5 100644 --- a/src/doc/rustdoc/src/how-to-write-documentation.md +++ b/src/doc/rustdoc/src/how-to-write-documentation.md @@ -256,7 +256,8 @@ So, no need to manually enter those Unicode characters! ### Adding a warning block -If you want to make a "warning" stand out in the documentation, you can wrap it like this: +If you want to make a warning or similar note stand out in the documentation, +you can wrap it like this: ```md /// documentation diff --git a/tests/rustdoc-gui/src/test_docs/lib.rs b/tests/rustdoc-gui/src/test_docs/lib.rs index 49484ee086960..38180aef762b4 100644 --- a/tests/rustdoc-gui/src/test_docs/lib.rs +++ b/tests/rustdoc-gui/src/test_docs/lib.rs @@ -65,6 +65,18 @@ impl Foo { pub fn must_use(&self) -> bool { true } + + /// hello + /// + ///
this is a warning
+ /// + /// done + pub fn warning1() {} + + /// Checking there is no bottom margin if "warning" is the last element. + /// + ///
this is a warning
+ pub fn warning2() {} } impl AsRef for Foo { diff --git a/tests/rustdoc-gui/warning-block.goml b/tests/rustdoc-gui/warning-block.goml new file mode 100644 index 0000000000000..2a935bd1a9bb5 --- /dev/null +++ b/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)", +})