[4/8] docs/sphinx: add CSS styling for qmp-example directive

Commit Message

John Snow July 3, 2024, 9:01 p.m. UTC

From: Harmonie Snow <[e-mail]>

Add CSS styling for qmp-example directives to increase readability and
consistently style all example blocks.

Signed-off-by: Harmonie Snow <[e-mail]>
Signed-off-by: John Snow <[e-mail]>
---
 docs/sphinx-static/theme_overrides.css | 49 ++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

Comments

Markus Armbruster July 9, 2024, 10:33 a.m. UTC | #1

John Snow <[e-mail]> writes:

> From: Harmonie Snow <[e-mail]>
>
> Add CSS styling for qmp-example directives to increase readability and
> consistently style all example blocks.
>
> Signed-off-by: Harmonie Snow <[e-mail]>
> Signed-off-by: John Snow <[e-mail]>

Same sadness as for the previous patch.

Acked-by: Markus Armbruster <[e-mail]>

John Snow July 9, 2024, 10:55 p.m. UTC | #2

On Tue, Jul 9, 2024 at 6:34 AM Markus Armbruster <[e-mail]> wrote:

> John Snow <[e-mail]> writes:
>
> > From: Harmonie Snow <[e-mail]>
> >
> > Add CSS styling for qmp-example directives to increase readability and
> > consistently style all example blocks.
> >
> > Signed-off-by: Harmonie Snow <[e-mail]>
> > Signed-off-by: John Snow <[e-mail]>
>
> Same sadness as for the previous patch.
>

Should we do anything about that? In the long run, I don't expect anyone
will actually need to care about what this directive looked like in some
intermediate state before we ever used it. If you want to evaluate the
directive in the in-between states, I recommend modifying a document and
seeing what it does; but I didn't really intend for anyone to really see it
that way.

(Isn't it a bit overboard to write unit tests for intermediate tree
states...?)


>
> Acked-by: Markus Armbruster <[e-mail]>
>
>

Markus Armbruster July 10, 2024, 4:37 a.m. UTC | #3

John Snow <[e-mail]> writes:

> On Tue, Jul 9, 2024 at 6:34 AM Markus Armbruster <[e-mail]> wrote:
>
>> John Snow <[e-mail]> writes:
>>
>> > From: Harmonie Snow <[e-mail]>
>> >
>> > Add CSS styling for qmp-example directives to increase readability and
>> > consistently style all example blocks.
>> >
>> > Signed-off-by: Harmonie Snow <[e-mail]>
>> > Signed-off-by: John Snow <[e-mail]>
>>
>> Same sadness as for the previous patch.
>>
>
> Should we do anything about that? In the long run, I don't expect anyone
> will actually need to care about what this directive looked like in some
> intermediate state before we ever used it. If you want to evaluate the
> directive in the in-between states, I recommend modifying a document and
> seeing what it does; but I didn't really intend for anyone to really see it
> that way.
>
> (Isn't it a bit overboard to write unit tests for intermediate tree
> states...?)

I'm not asking for temporary tests, I just wonder why you delay
permanent ones until "[PATCH 8/8] qapi: remove "Example" doc section".

No big deal, thus:

>> Acked-by: Markus Armbruster <[e-mail]>

Patch

diff --git a/docs/sphinx-static/theme_overrides.css b/docs/sphinx-static/theme_overrides.css
index c70ef951286..965ecac54fd 100644
--- a/docs/sphinx-static/theme_overrides.css
+++ b/docs/sphinx-static/theme_overrides.css
@@ -87,6 +87,55 @@  div[class^="highlight"] pre {
     padding-bottom: 1px;
 }
 
+/* qmp-example directive styling */
+
+.rst-content .admonition-example {
+    /* do not apply the standard admonition background */
+    background-color: transparent;
+    border: solid #ffd2ed 1px;
+}
+
+.rst-content .admonition-example > .admonition-title:before {
+    content: "▷";
+}
+
+.rst-content .admonition-example > .admonition-title {
+    background-color: #5980a6;
+}
+
+.rst-content .admonition-example > div[class^="highlight"] {
+    /* make code boxes take up the full width of the admonition w/o margin */
+    margin-left: -12px;
+    margin-right: -12px;
+
+    border-top: 1px solid #ffd2ed;
+    border-bottom: 1px solid #ffd2ed;
+    border-left: 0px;
+    border-right: 0px;
+}
+
+.rst-content .admonition-example > div[class^="highlight"]:nth-child(2) {
+    /* If a code box is the second element in an example admonition,
+     * it is the first child after the title. let it sit flush against
+     * the title. */
+    margin-top: -12px;
+    border-top: 0px;
+}
+
+.rst-content .admonition-example > div[class^="highlight"]:last-child {
+    /* If a code box is the final element in an example admonition, don't
+     * render margin below it; let it sit flush with the end of the
+     * admonition box */
+    margin-bottom: -12px;
+    border-bottom: 0px;
+}
+
+.rst-content .admonition-example .highlight {
+    background-color: #fffafd;
+}
+
+/* end qmp-example styling */
+
 @media screen {
 
     /* content column