Skip to content

Commit

Permalink
Auto merge of #106561 - GuillaumeGomez:warning-block, r=rustdoc
Browse files Browse the repository at this point in the history
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`
  • Loading branch information
bors committed Aug 21, 2023
2 parents c40cfcf + 1d42913 commit 5e9d3d8
Show file tree
Hide file tree
Showing 7 changed files with 96 additions and 3 deletions.
13 changes: 13 additions & 0 deletions src/doc/rustdoc/src/how-to-write-documentation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/
Expand Down
26 changes: 23 additions & 3 deletions src/librustdoc/html/static/css/rustdoc.css
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}

Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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;
Expand Down
1 change: 1 addition & 0 deletions src/librustdoc/html/static/css/themes/ayu.css
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
1 change: 1 addition & 0 deletions src/librustdoc/html/static/css/themes/dark.css
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
1 change: 1 addition & 0 deletions src/librustdoc/html/static/css/themes/light.css
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
12 changes: 12 additions & 0 deletions tests/rustdoc-gui/src/test_docs/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
45 changes: 45 additions & 0 deletions tests/rustdoc-gui/warning-block.goml
Original file line number Diff line number Diff line change
@@ -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)",
})

0 comments on commit 5e9d3d8

Please sign in to comment.