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

Patchew URL: https://patchew.org/QEMU/20201105160335.1222062-1-marcandre.lureau@redhat.com/



Hi,

This series seems to have some coding style problems. See output below for
more information:

Type: series
Message-id: 20201105160335.1222062-1-marcandre.lureau@redhat.com
Subject: [PATCH] RFC: sphinx: adopt kernel readthedoc theme

=== TEST SCRIPT BEGIN ===
#!/bin/bash
git rev-parse base > /dev/null || exit 0
git config --local diff.renamelimit 0
git config --local diff.renames True
git config --local diff.algorithm histogram
./scripts/checkpatch.pl --mailback base..
=== TEST SCRIPT END ===

Updating 3c8cf5a9c21ff8782164d1def7f44bd888713384
From https://github.com/patchew-project/qemu
 * [new tag]         patchew/20201105160335.1222062-1-marcandre.lureau@redhat.com -> patchew/20201105160335.1222062-1-marcandre.lureau@redhat.com
 - [tag update]      patchew/5FA41448.4040404@huawei.com -> patchew/5FA41448.4040404@huawei.com
Switched to a new branch 'test'
6c91276 RFC: sphinx: adopt kernel readthedoc theme

=== OUTPUT BEGIN ===
ERROR: line over 90 characters
#38: FILE: docs/conf.py:157:
+    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')

WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
#126: 
new file mode 100644

total: 1 errors, 1 warnings, 232 lines checked

Commit 6c912763d717 (RFC: sphinx: adopt kernel readthedoc theme) has style problems, please review.  If any of these errors
are false positives report them to the maintainer, see
CHECKPATCH in MAINTAINERS.
=== OUTPUT END ===

Test command exited with code: 1


The full log is available at
http://patchew.org/logs/20201105160335.1222062-1-marcandre.lureau@redhat.com/testing.checkpatch/?type=message.
---
Email generated automatically by Patchew [https://patchew.org/].
Please send your feedback to patchew-devel@redhat.com

Hi,

On Thu, Nov 5, 2020 at 8:03 PM <marcandre.lureau@redhat.com> wrote:
>
> 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
>

Am I the only one finding the default sphinx theme inferior to rtd ?

thanks

On Mon, Nov 16, 2020 at 6:57 PM Marc-André Lureau
<marcandre.lureau@redhat.com> wrote:
>
> Hi,
>
> On Thu, Nov 5, 2020 at 8:03 PM <marcandre.lureau@redhat.com> wrote:
> >
> > 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
> >
>
> Am I the only one finding the default sphinx theme inferior to rtd ?

Of course not!

This patch does not apply on top of current HEAD. Could you please rebase?

Regards,
Bin

On 11/16/20 5:56 AM, Marc-André Lureau wrote:
> Hi,
> 
> On Thu, Nov 5, 2020 at 8:03 PM <marcandre.lureau@redhat.com> wrote:
>>
>> 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
>>
> 
> Am I the only one finding the default sphinx theme inferior to rtd ?
> 
> thanks
> 
> 

Probably not, but do you have some screenshots or examples of before/after?

--js