[PATCH] RFC: sphinx: adopt kernel readthedoc theme

[marcandre . lureau]

From: Marc-André Lureau <marcandre.lureau@redhat.com>

The default "alabaster" sphinx theme has a couple shortcomings:
- the navbar moves along the page
- the search bar is not always at the same place
- it lacks some contrast and colours

The "rtd" theme from readthedocs.org is a popular third party theme used
notably by the kernel, with a custom style sheet. I like it better,
perhaps others do too. It also has features that may come handy, such as
"Edit on Gitlab".

Tweak the nav header background to match qemu.org style, use the
QEMU logo, and favicon.

The html_theme_options['description'] workaround doesn't seem necessary.

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/conf.py                           |  36 +++----
 docs/devel/conf.py                     |   4 -
 docs/interop/conf.py                   |   4 -
 docs/specs/conf.py                     |   5 -
 docs/sphinx-static/theme_overrides.css | 137 +++++++++++++++++++++++++
 docs/system/conf.py                    |   4 -
 docs/tools/conf.py                     |   5 -
 docs/user/conf.py                      |   4 -
 8 files changed, 155 insertions(+), 44 deletions(-)
 create mode 100644 docs/sphinx-static/theme_overrides.css

diff --git a/docs/conf.py b/docs/conf.py
index e584f68393..54c4e1e687 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -150,37 +150,37 @@ with open(os.path.join(qemu_docdir, 'defs.rst.inc')) as f:
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+try:
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+except ImportError:
+    sys.stderr.write('Warning: The Sphinx \'sphinx_rtd_theme\' HTML theme was 
not found. Make sure you have the theme installed to produce pretty HTML 
output. Falling back to the default theme.\n')
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-# We initialize this to empty here, so the per-manual conf.py can just
-# add individual key/value entries.
 html_theme_options = {
+    "style_nav_header_background": "#802400",
 }
 
+html_logo = os.path.join(qemu_docdir, "../ui/icons/qemu_128x128.png")
+
+html_favicon = os.path.join(qemu_docdir, "../ui/icons/qemu_32x32.png")
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-# QEMU doesn't yet have any static files, so comment this out so we don't
-# get a warning about a missing directory.
-# If we do ever add this then it would probably be better to call the
-# subdirectory sphinx_static, as the Linux kernel does.
-# html_static_path = ['_static']
+html_static_path = [os.path.join(qemu_docdir, "sphinx-static")]
+
+html_context = {
+    'css_files': [
+        '_static/theme_overrides.css',
+    ],
+}
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
-#
-# This is required for the alabaster theme
-# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
-html_sidebars = {
-    '**': [
-        'about.html',
-        'navigation.html',
-        'searchbox.html',
-    ]
-}
+#html_sidebars = {}
 
 # Don't copy the rST source files to the HTML output directory,
 # and don't put links to the sources into the output HTML.
diff --git a/docs/devel/conf.py b/docs/devel/conf.py
index 7441f87e7f..f0905b728b 100644
--- a/docs/devel/conf.py
+++ b/docs/devel/conf.py
@@ -9,7 +9,3 @@ import os
 qemu_docdir = os.path.abspath("..")
 parent_config = os.path.join(qemu_docdir, "conf.py")
 exec(compile(open(parent_config, "rb").read(), parent_config, 'exec'))
-
-# This slightly misuses the 'description', but is the best way to get
-# the manual title to appear in the sidebar.
-html_theme_options['description'] = u'Developer''s Guide'
diff --git a/docs/interop/conf.py b/docs/interop/conf.py
index 2634ca3410..97d9e8c116 100644
--- a/docs/interop/conf.py
+++ b/docs/interop/conf.py
@@ -10,10 +10,6 @@ qemu_docdir = os.path.abspath("..")
 parent_config = os.path.join(qemu_docdir, "conf.py")
 exec(compile(open(parent_config, "rb").read(), parent_config, 'exec'))
 
-# This slightly misuses the 'description', but is the best way to get
-# the manual title to appear in the sidebar.
-html_theme_options['description'] = u'System Emulation Management and 
Interoperability Guide'
-
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
diff --git a/docs/specs/conf.py b/docs/specs/conf.py
index 4d56f3ae13..1be2d3bd20 100644
--- a/docs/specs/conf.py
+++ b/docs/specs/conf.py
@@ -9,8 +9,3 @@ import os
 qemu_docdir = os.path.abspath("..")
 parent_config = os.path.join(qemu_docdir, "conf.py")
 exec(compile(open(parent_config, "rb").read(), parent_config, 'exec'))
-
-# This slightly misuses the 'description', but is the best way to get
-# the manual title to appear in the sidebar.
-html_theme_options['description'] = \
-    u'System Emulation Guest Hardware Specifications'
diff --git a/docs/sphinx-static/theme_overrides.css 
b/docs/sphinx-static/theme_overrides.css
new file mode 100644
index 0000000000..00bcb40bd7
--- /dev/null
+++ b/docs/sphinx-static/theme_overrides.css
@@ -0,0 +1,137 @@
+/* -*- coding: utf-8; mode: css -*-
+ *
+ * Sphinx HTML theme customization: read the doc
+ * Based on Linux Documentation/sphinx-static/theme_overrides.css
+ */
+
+/* Improve contrast and increase size for easier reading. */
+
+body {
+    font-family: serif;
+    color: black;
+    font-size: 100%;
+}
+
+h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend {
+    font-family: sans-serif;
+}
+
+.wy-menu-vertical li.current a {
+    color: #505050;
+}
+
+.wy-menu-vertical li.on a, .wy-menu-vertical li.current > a {
+    color: #303030;
+}
+
+div[class^="highlight"] pre {
+    font-family: monospace;
+    color: black;
+    font-size: 100%;
+}
+
+.wy-menu-vertical {
+    font-family: sans-serif;
+}
+
+.c {
+    font-style: normal;
+}
+
+p {
+    font-size: 100%;
+}
+
+/* Interim: Code-blocks with line nos - lines and line numbers don't line up.
+ * see: https://github.com/rtfd/sphinx_rtd_theme/issues/419
+ */
+
+div[class^="highlight"] pre {
+    line-height: normal;
+}
+.rst-content .highlight > pre {
+    line-height: normal;
+}
+
+/* Keep fields from being strangely far apart due to inheirited table CSS. */
+.rst-content table.field-list th.field-name {
+    padding-top: 1px;
+    padding-bottom: 1px;
+}
+.rst-content table.field-list td.field-body {
+    padding-top: 1px;
+    padding-bottom: 1px;
+}
+
+@media screen {
+
+    /* content column
+     *
+     * RTD theme's default is 800px as max width for the content, but we have
+     * tables with tons of columns, which need the full width of the view-port.
+     */
+
+    .wy-nav-content{max-width: none; }
+
+    /* table:
+     *
+     *   - Sequences of whitespace should collapse into a single whitespace.
+     *   - make the overflow auto (scrollbar if needed)
+     *   - align caption "left" ("center" is unsuitable on vast tables)
+     */
+
+    .wy-table-responsive table td { white-space: normal; }
+    .wy-table-responsive { overflow: auto; }
+    .rst-content table.docutils caption { text-align: left; font-size: 100%; }
+
+    /* captions:
+     *
+     *   - captions should have 100% (not 85%) font size
+     *   - hide the permalink symbol as long as link is not hovered
+     */
+
+    .toc-title {
+        font-size: 150%;
+        font-weight: bold;
+    }
+
+    caption, .wy-table caption, .rst-content table.field-list caption {
+        font-size: 100%;
+    }
+    caption a.headerlink { opacity: 0; }
+    caption a.headerlink:hover { opacity: 1; }
+
+    /* Menu selection and keystrokes */
+
+    span.menuselection {
+        color: blue;
+        font-family: "Courier New", Courier, monospace
+    }
+
+    code.kbd, code.kbd span {
+        color: white;
+        background-color: darkblue;
+        font-weight: bold;
+        font-family: "Courier New", Courier, monospace
+    }
+
+    /* fix bottom margin of lists items */
+
+    .rst-content .section ul li:last-child, .rst-content .section ul li 
p:last-child {
+          margin-bottom: 12px;
+    }
+
+    /* inline literal: drop the borderbox, padding and red color */
+
+    code, .rst-content tt, .rst-content code {
+        color: inherit;
+        border: none;
+        padding: unset;
+        background: inherit;
+        font-size: 85%;
+    }
+
+    .rst-content tt.literal,.rst-content tt.literal,.rst-content code.literal {
+        color: inherit;
+    }
+}
diff --git a/docs/system/conf.py b/docs/system/conf.py
index 6251849fef..847cd87fa2 100644
--- a/docs/system/conf.py
+++ b/docs/system/conf.py
@@ -10,10 +10,6 @@ qemu_docdir = os.path.abspath("..")
 parent_config = os.path.join(qemu_docdir, "conf.py")
 exec(compile(open(parent_config, "rb").read(), parent_config, 'exec'))
 
-# This slightly misuses the 'description', but is the best way to get
-# the manual title to appear in the sidebar.
-html_theme_options['description'] = u'System Emulation User''s Guide'
-
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
diff --git a/docs/tools/conf.py b/docs/tools/conf.py
index 9052d17d6d..a11923a786 100644
--- a/docs/tools/conf.py
+++ b/docs/tools/conf.py
@@ -10,11 +10,6 @@ qemu_docdir = os.path.abspath("..")
 parent_config = os.path.join(qemu_docdir, "conf.py")
 exec(compile(open(parent_config, "rb").read(), parent_config, 'exec'))
 
-# This slightly misuses the 'description', but is the best way to get
-# the manual title to appear in the sidebar.
-html_theme_options['description'] = \
-    u'Tools Guide'
-
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
diff --git a/docs/user/conf.py b/docs/user/conf.py
index 4b09aedd45..7b89273d43 100644
--- a/docs/user/conf.py
+++ b/docs/user/conf.py
@@ -9,7 +9,3 @@ import os
 qemu_docdir = os.path.abspath("..")
 parent_config = os.path.join(qemu_docdir, "conf.py")
 exec(compile(open(parent_config, "rb").read(), parent_config, 'exec'))
-
-# This slightly misuses the 'description', but is the best way to get
-# the manual title to appear in the sidebar.
-html_theme_options['description'] = u'User Mode Emulation User''s Guide'
-- 
2.29.0