Improve the general look and feel of generated QAPI docs.

Attempt to limit line lengths to offer a more comfortable measure on
maximized windows, and improve some margin and spacing for field lists.

Signed-off-by: Harmonie Snow <harmonie@gmail.com>
Signed-off-by: John Snow <jsnow@redhat.com>
---
 docs/sphinx-static/theme_overrides.css | 56 +++++++++++++++++++++++++-
 1 file changed, 54 insertions(+), 2 deletions(-)

diff --git a/docs/sphinx-static/theme_overrides.css b/docs/sphinx-static/theme_overrides.css
index 3fd326613d9..92f395054a8 100644
--- a/docs/sphinx-static/theme_overrides.css
+++ b/docs/sphinx-static/theme_overrides.css
@@ -18,8 +18,8 @@ h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend {
 
 .rst-content dl:not(.docutils) dt {
     border-top: none;
-    border-left: solid 3px #ccc;
-    background-color: #f0f0f0;
+    border-left: solid 5px #bcc6d2;
+    background-color: #eaedf1;
     color: black;
 }
 
@@ -211,6 +211,18 @@ div[class^="highlight"] pre {
 
 /* QAPI domain theming */
 
+/* most content in a qapi object definition should not eclipse about
+   80ch, but nested field lists are explicitly exempt due to their
+   two-column nature */
+.qapi dd *:not(dl) {
+    max-width: 80ch;
+}
+
+/* but the content column itself should still be less than ~80ch. */
+.qapi .field-list dd {
+    max-width: 80ch;
+}
+
 .qapi-infopips {
     margin-bottom: 1em;
 }
@@ -250,3 +262,43 @@ div[class^="highlight"] pre {
     border-radius: 15px;
     margin: 5px;
 }
+
+/* code blocks */
+.qapi div[class^="highlight"] {
+    width: fit-content;
+    background-color: #fffafd;
+    border: 2px solid #ffe1f3;
+}
+
+/* note, warning, etc. */
+.qapi .admonition {
+    width: fit-content;
+}
+
+/* pad the top of the field-list so the text doesn't start directly at
+   the top border; primarily for the field list labels, but adjust the
+   field bodies as well for parity. */
+dl.field-list > dt:first-of-type, dl.field-list > dd:first-of-type {
+    padding-top: 0.3em;
+}
+
+dl.field-list > dt:last-of-type, dl.field-list > dd:last-of-type {
+    padding-bottom: 0.3em;
+}
+
+/* pad the field list labels so they don't crash into the border */
+dl.field-list > dt {
+    padding-left: 0.5em;
+    padding-right: 0.5em;
+}
+
+/* Add a little padding between field list sections */
+dl.field-list > dd:not(:last-child) {
+    padding-bottom: 1em;
+}
+
+/* Sphinx 3.x: unresolved xrefs */
+.rst-content *:not(a) > code.xref {
+    font-weight: 400;
+    color: #333333;
+}
-- 
2.48.1

John Snow <jsnow@redhat.com> writes:

> Improve the general look and feel of generated QAPI docs.
>
> Attempt to limit line lengths to offer a more comfortable measure on
> maximized windows, and improve some margin and spacing for field lists.
>
> Signed-off-by: Harmonie Snow <harmonie@gmail.com>
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  docs/sphinx-static/theme_overrides.css | 56 +++++++++++++++++++++++++-
>  1 file changed, 54 insertions(+), 2 deletions(-)
>
> diff --git a/docs/sphinx-static/theme_overrides.css b/docs/sphinx-static/theme_overrides.css
> index 3fd326613d9..92f395054a8 100644
> --- a/docs/sphinx-static/theme_overrides.css
> +++ b/docs/sphinx-static/theme_overrides.css
> @@ -18,8 +18,8 @@ h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend {
>  
>  .rst-content dl:not(.docutils) dt {
>      border-top: none;
> -    border-left: solid 3px #ccc;
> -    background-color: #f0f0f0;
> +    border-left: solid 5px #bcc6d2;
> +    background-color: #eaedf1;
>      color: black;
>  }
>  
> @@ -211,6 +211,18 @@ div[class^="highlight"] pre {
>  
>  /* QAPI domain theming */
>  
> +/* most content in a qapi object definition should not eclipse about

QAPI unless there's a reason for lower case.

> +   80ch, but nested field lists are explicitly exempt due to their
> +   two-column nature */
> +.qapi dd *:not(dl) {
> +    max-width: 80ch;
> +}
> +
> +/* but the content column itself should still be less than ~80ch. */
> +.qapi .field-list dd {
> +    max-width: 80ch;
> +}
> +
>  .qapi-infopips {
>      margin-bottom: 1em;
>  }

[...]