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 simplify "Edit on Gitlab" links.

Tweak a bit the custom theme to match qemu.org style, use the
QEMU logo, and favicon etc.

Screenshot:
https://i.ibb.co/XWwG1bZ/Screenshot-2021-01-20-Welcome-to-QEMU-s-documentation-QEMU-documentation.png

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Tested-by: Bin Meng <bmeng.cn@gmail.com>
---
v4:
 - resend (with Bin T-b, and with minor style fixes)

 docs/_templates/editpage.html              |   5 -
 docs/conf.py                               |  50 ++++---
 docs/devel/_templates/editpage.html        |   5 -
 docs/interop/_templates/editpage.html      |   5 -
 docs/specs/_templates/editpage.html        |   5 -
 docs/sphinx-static/theme_overrides.css     | 161 +++++++++++++++++++++
 docs/system/_templates/editpage.html       |   5 -
 docs/tools/_templates/editpage.html        |   5 -
 docs/user/_templates/editpage.html         |   5 -
 tests/docker/dockerfiles/debian10.docker   |   1 +
 tests/docker/dockerfiles/fedora.docker     |   1 +
 tests/docker/dockerfiles/ubuntu.docker     |   1 +
 tests/docker/dockerfiles/ubuntu1804.docker |   1 +
 tests/docker/dockerfiles/ubuntu2004.docker |   1 +
 14 files changed, 196 insertions(+), 55 deletions(-)
 delete mode 100644 docs/_templates/editpage.html
 delete mode 100644 docs/devel/_templates/editpage.html
 delete mode 100644 docs/interop/_templates/editpage.html
 delete mode 100644 docs/specs/_templates/editpage.html
 create mode 100644 docs/sphinx-static/theme_overrides.css
 delete mode 100644 docs/system/_templates/editpage.html
 delete mode 100644 docs/tools/_templates/editpage.html
 delete mode 100644 docs/user/_templates/editpage.html

diff --git a/docs/_templates/editpage.html b/docs/_templates/editpage.html
deleted file mode 100644
index 4319b0f5ac..0000000000
--- a/docs/_templates/editpage.html
+++ /dev/null
@@ -1,5 +0,0 @@
-<div id="editpage">
-  <ul>
-    <li><a href="https://gitlab.com/qemu-project/qemu/-/blob/master/docs/{{pagename}}.rst">Page source</a></li>
-  </ul>
-</div>
diff --git a/docs/conf.py b/docs/conf.py
index 2ee6111872..17e0319d69 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -151,37 +151,47 @@
 # 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 = {
-}
+if html_theme == 'sphinx_rtd_theme':
+    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_css_files = [
+    'theme_overrides.css',
+]
+
+html_context = {
+    "display_gitlab": True,
+    "gitlab_user": "qemu-project",
+    "gitlab_repo": "qemu",
+    "gitlab_version": "master",
+    "conf_py_path": "/docs/", # Path in the checkout to the docs root
+}
 
 # 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',
-        'editpage.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/_templates/editpage.html b/docs/devel/_templates/editpage.html
deleted file mode 100644
index a86d22bca8..0000000000
--- a/docs/devel/_templates/editpage.html
+++ /dev/null
@@ -1,5 +0,0 @@
-<div id="editpage">
-  <ul>
-    <li><a href="https://gitlab.com/qemu-project/qemu/-/blob/master/docs/devel/{{pagename}}.rst">Page source</a></li>
-  </ul>
-</div>
diff --git a/docs/interop/_templates/editpage.html b/docs/interop/_templates/editpage.html
deleted file mode 100644
index 215e562681..0000000000
--- a/docs/interop/_templates/editpage.html
+++ /dev/null
@@ -1,5 +0,0 @@
-<div id="editpage">
-  <ul>
-    <li><a href="https://gitlab.com/qemu-project/qemu/-/blob/master/docs/interop/{{pagename}}.rst">Page source</a></li>
-  </ul>
-</div>
diff --git a/docs/specs/_templates/editpage.html b/docs/specs/_templates/editpage.html
deleted file mode 100644
index aaa468aa98..0000000000
--- a/docs/specs/_templates/editpage.html
+++ /dev/null
@@ -1,5 +0,0 @@
-<div id="editpage">
-  <ul>
-    <li><a href="https://gitlab.com/qemu-project/qemu/-/blob/master/docs/specs/{{pagename}}.rst">Page source</a></li>
-  </ul>
-</div>
diff --git a/docs/sphinx-static/theme_overrides.css b/docs/sphinx-static/theme_overrides.css
new file mode 100644
index 0000000000..c70ef95128
--- /dev/null
+++ b/docs/sphinx-static/theme_overrides.css
@@ -0,0 +1,161 @@
+/* -*- 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;
+}
+
+.rst-content dl:not(.docutils) dt {
+    border-top: none;
+    border-left: solid 3px #ccc;
+    background-color: #f0f0f0;
+    color: black;
+}
+
+.wy-nav-top {
+    background: #802400;
+}
+
+.wy-side-nav-search input[type="text"] {
+    border-color: #f60;
+}
+
+.wy-menu-vertical p.caption {
+    color: white;
+}
+
+.wy-menu-vertical li.current a {
+    color: #505050;
+}
+
+.wy-menu-vertical li.on a, .wy-menu-vertical li.current > a {
+    color: #303030;
+}
+
+.fa-gitlab {
+      box-shadow: 0 4px 8px 0 rgba(0,0,0,0.2), 0 3px 10px 0 rgba(0,0,0,0.19);
+      border-radius: 5px;
+}
+
+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/_templates/editpage.html b/docs/system/_templates/editpage.html
deleted file mode 100644
index 6586b2e257..0000000000
--- a/docs/system/_templates/editpage.html
+++ /dev/null
@@ -1,5 +0,0 @@
-<div id="editpage">
-  <ul>
-    <li><a href="https://gitlab.com/qemu-project/qemu/-/blob/master/docs/system/{{pagename}}.rst">Page source</a></li>
-  </ul>
-</div>
diff --git a/docs/tools/_templates/editpage.html b/docs/tools/_templates/editpage.html
deleted file mode 100644
index 2a9c8fc92b..0000000000
--- a/docs/tools/_templates/editpage.html
+++ /dev/null
@@ -1,5 +0,0 @@
-<div id="editpage">
-  <ul>
-    <li><a href="https://gitlab.com/qemu-project/qemu/-/blob/master/docs/tools/{{pagename}}.rst">Page source</a></li>
-  </ul>
-</div>
diff --git a/docs/user/_templates/editpage.html b/docs/user/_templates/editpage.html
deleted file mode 100644
index 1f5ee01e60..0000000000
--- a/docs/user/_templates/editpage.html
+++ /dev/null
@@ -1,5 +0,0 @@
-<div id="editpage">
-  <ul>
-    <li><a href="https://gitlab.com/qemu-project/qemu/-/blob/master/docs/user/{{pagename}}.rst">Page source</a></li>
-  </ul>
-</div>
diff --git a/tests/docker/dockerfiles/debian10.docker b/tests/docker/dockerfiles/debian10.docker
index d034acbd25..63cf835ec5 100644
--- a/tests/docker/dockerfiles/debian10.docker
+++ b/tests/docker/dockerfiles/debian10.docker
@@ -32,6 +32,7 @@ RUN apt update && \
         psmisc \
         python3 \
         python3-sphinx \
+        python3-sphinx-rtd-theme \
         $(apt-get -s build-dep --arch-only qemu | egrep ^Inst | fgrep '[all]' | cut -d\  -f2)
 
 ENV FEATURES docs
diff --git a/tests/docker/dockerfiles/fedora.docker b/tests/docker/dockerfiles/fedora.docker
index 915fdc1845..d8fa16372d 100644
--- a/tests/docker/dockerfiles/fedora.docker
+++ b/tests/docker/dockerfiles/fedora.docker
@@ -92,6 +92,7 @@ ENV PACKAGES \
     python3-pillow \
     python3-pip \
     python3-sphinx \
+    python3-sphinx_rtd_theme \
     python3-virtualenv \
     rdma-core-devel \
     SDL2-devel \
diff --git a/tests/docker/dockerfiles/ubuntu.docker b/tests/docker/dockerfiles/ubuntu.docker
index b5ef7a8198..98a527361c 100644
--- a/tests/docker/dockerfiles/ubuntu.docker
+++ b/tests/docker/dockerfiles/ubuntu.docker
@@ -63,6 +63,7 @@ ENV PACKAGES \
     ninja-build \
     python3-yaml \
     python3-sphinx \
+    python3-sphinx-rtd-theme \
     sparse \
     xfslibs-dev
 RUN apt-get update && \
diff --git a/tests/docker/dockerfiles/ubuntu1804.docker b/tests/docker/dockerfiles/ubuntu1804.docker
index 9b0a19ba5e..c0d3642507 100644
--- a/tests/docker/dockerfiles/ubuntu1804.docker
+++ b/tests/docker/dockerfiles/ubuntu1804.docker
@@ -48,6 +48,7 @@ ENV PACKAGES \
     make \
     python3-yaml \
     python3-sphinx \
+    python3-sphinx-rtd-theme \
     ninja-build \
     sparse \
     xfslibs-dev
diff --git a/tests/docker/dockerfiles/ubuntu2004.docker b/tests/docker/dockerfiles/ubuntu2004.docker
index 9750016e51..f1e0ebad49 100644
--- a/tests/docker/dockerfiles/ubuntu2004.docker
+++ b/tests/docker/dockerfiles/ubuntu2004.docker
@@ -58,6 +58,7 @@ ENV PACKAGES flex bison \
     python3-pil \
     python3-pip \
     python3-sphinx \
+    python3-sphinx-rtd-theme \
     python3-venv \
     python3-yaml \
     rpm2cpio \
-- 
2.29.0

On Mon, Mar 22, 2021 at 02:52:34PM +0400, 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 simplify "Edit on Gitlab" links.

s/simplify/simplifies the/

> 
> Tweak a bit the custom theme to match qemu.org style, use the
> QEMU logo, and favicon etc.
> 
> Screenshot:
> https://i.ibb.co/XWwG1bZ/Screenshot-2021-01-20-Welcome-to-QEMU-s-documentation-QEMU-documentation.png

I'd drop this from the commit message unless you're confident
this link will remain alive indefinitely.

> 
> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> Tested-by: Bin Meng <bmeng.cn@gmail.com>
> ---
> v4:
>  - resend (with Bin T-b, and with minor style fixes)
> 
>  docs/_templates/editpage.html              |   5 -
>  docs/conf.py                               |  50 ++++---
>  docs/devel/_templates/editpage.html        |   5 -
>  docs/interop/_templates/editpage.html      |   5 -
>  docs/specs/_templates/editpage.html        |   5 -
>  docs/sphinx-static/theme_overrides.css     | 161 +++++++++++++++++++++
>  docs/system/_templates/editpage.html       |   5 -
>  docs/tools/_templates/editpage.html        |   5 -
>  docs/user/_templates/editpage.html         |   5 -
>  tests/docker/dockerfiles/debian10.docker   |   1 +
>  tests/docker/dockerfiles/fedora.docker     |   1 +
>  tests/docker/dockerfiles/ubuntu.docker     |   1 +
>  tests/docker/dockerfiles/ubuntu1804.docker |   1 +
>  tests/docker/dockerfiles/ubuntu2004.docker |   1 +
>  14 files changed, 196 insertions(+), 55 deletions(-)
>  delete mode 100644 docs/_templates/editpage.html
>  delete mode 100644 docs/devel/_templates/editpage.html
>  delete mode 100644 docs/interop/_templates/editpage.html
>  delete mode 100644 docs/specs/_templates/editpage.html
>  create mode 100644 docs/sphinx-static/theme_overrides.css
>  delete mode 100644 docs/system/_templates/editpage.html
>  delete mode 100644 docs/tools/_templates/editpage.html
>  delete mode 100644 docs/user/_templates/editpage.html
> 
> diff --git a/docs/_templates/editpage.html b/docs/_templates/editpage.html
> deleted file mode 100644
> index 4319b0f5ac..0000000000
> --- a/docs/_templates/editpage.html
> +++ /dev/null
> @@ -1,5 +0,0 @@
> -<div id="editpage">
> -  <ul>
> -    <li><a href="https://gitlab.com/qemu-project/qemu/-/blob/master/docs/{{pagename}}.rst">Page source</a></li>
> -  </ul>
> -</div>
> diff --git a/docs/conf.py b/docs/conf.py
> index 2ee6111872..17e0319d69 100644
> --- a/docs/conf.py
> +++ b/docs/conf.py
> @@ -151,37 +151,47 @@
>  # 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 = {
> -}
> +if html_theme == 'sphinx_rtd_theme':
> +    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_css_files = [
> +    'theme_overrides.css',
> +]

Does this still have a good result in the case where we fall back
to alabaster theme ?

> +
> +html_context = {
> +    "display_gitlab": True,
> +    "gitlab_user": "qemu-project",
> +    "gitlab_repo": "qemu",
> +    "gitlab_version": "master",
> +    "conf_py_path": "/docs/", # Path in the checkout to the docs root
> +}
>  
>  # 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',
> -        'editpage.html',
> -        'navigation.html',
> -        'searchbox.html',
> -    ]
> -}

Aren't these still needed when we fall back to the alabaster theme ?

Well the editpage.html can be dropped without real harm, but the
navigation.html looks pretty important to me.

> +#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.




Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

On Tue, 23 Mar 2021 at 10:27, Daniel P. Berrangé <berrange@redhat.com> wrote:
>
> On Mon, Mar 22, 2021 at 02:52:34PM +0400, 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 simplify "Edit on Gitlab" links.

> >  # 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_css_files = [
> > +    'theme_overrides.css',
> > +]
>
> Does this still have a good result in the case where we fall back
> to alabaster theme ?

How much do we want to retain support for multiple themes? When
I was first putting in the Sphinx documentation I found that some
things were kind of theme-specific, in that tweaking things to look
and read sensibly in one theme made them look a bit weird in another.
If we said "we support only the rtd theme and mandate it" would that
cause much pain for downstreams and end-users ?

thanks
-- PMM

Hi

On Tue, Mar 23, 2021 at 3:01 PM Peter Maydell <peter.maydell@linaro.org>
wrote:

> On Tue, 23 Mar 2021 at 10:27, Daniel P. Berrangé <berrange@redhat.com>
> wrote:
> >
> > On Mon, Mar 22, 2021 at 02:52:34PM +0400, 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 simplify "Edit on Gitlab" links.
>
> > >  # 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_css_files = [
> > > +    'theme_overrides.css',
> > > +]
> >
> > Does this still have a good result in the case where we fall back
> > to alabaster theme ?
>
> How much do we want to retain support for multiple themes? When
> I was first putting in the Sphinx documentation I found that some
> things were kind of theme-specific, in that tweaking things to look
> and read sensibly in one theme made them look a bit weird in another.
> If we said "we support only the rtd theme and mandate it" would that
> cause much pain for downstreams and end-users ?
>

I don't expect it to be a problem: with this patch, we have the same
requirement as the kernel: rtd is the default supported theme, alabaster is
a fallback (with the minor styles hiccups/incompatibilities it may have)


-- 
Marc-André Lureau

On Tue, Mar 23, 2021 at 11:00:29AM +0000, Peter Maydell wrote:
> On Tue, 23 Mar 2021 at 10:27, Daniel P. Berrangé <berrange@redhat.com> wrote:
> >
> > On Mon, Mar 22, 2021 at 02:52:34PM +0400, 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 simplify "Edit on Gitlab" links.
> 
> > >  # 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_css_files = [
> > > +    'theme_overrides.css',
> > > +]
> >
> > Does this still have a good result in the case where we fall back
> > to alabaster theme ?
> 
> How much do we want to retain support for multiple themes? When
> I was first putting in the Sphinx documentation I found that some
> things were kind of theme-specific, in that tweaking things to look
> and read sensibly in one theme made them look a bit weird in another.
> If we said "we support only the rtd theme and mandate it" would that
> cause much pain for downstreams and end-users ?

The theme is pre-packaged for Fedora, Debian, Ubuntu, which gives me
confidence for Linux distros in general.

BSD / macOS / Windows, who knows ?

We could check for rtd theme in meson, and disable the docs build
if missing.  Might be better than pretending to have alabaster
fallback which none of us will ever test, and then get bugs about
it.


Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

On Tue, 23 Mar 2021 at 11:29, Daniel P. Berrangé <berrange@redhat.com> wrote:
> The theme is pre-packaged for Fedora, Debian, Ubuntu, which gives me
> confidence for Linux distros in general.
>
> BSD / macOS / Windows, who knows ?

Mmm, good point. Marc-André's the one who's been doing the work
here, so I'm happy to leave it up to him if he thinks retaining
the fallback is the best approach.

> We could check for rtd theme in meson, and disable the docs build
> if missing.

If you make the docs/conf.py raise an error if the theme is missing,
then the existing docs/meson.build "does sphinx work?" test will
disable the docs build. (You would want to improve the error message
to note that the problem might be missing theme, though.)

thanks
-- PMM

Hi

On Tue, Mar 23, 2021 at 3:36 PM Peter Maydell <peter.maydell@linaro.org>
wrote:

> On Tue, 23 Mar 2021 at 11:29, Daniel P. Berrangé <berrange@redhat.com>
> wrote:
> > The theme is pre-packaged for Fedora, Debian, Ubuntu, which gives me
> > confidence for Linux distros in general.
> >
> > BSD / macOS / Windows, who knows ?
>
> Mmm, good point. Marc-André's the one who's been doing the work
> here, so I'm happy to leave it up to him if he thinks retaining
> the fallback is the best approach.
>
> > We could check for rtd theme in meson, and disable the docs build
> > if missing.
>
> If you make the docs/conf.py raise an error if the theme is missing,
> then the existing docs/meson.build "does sphinx work?" test will
> disable the docs build. (You would want to improve the error message
> to note that the problem might be missing theme, though.)
>
>
Ok great, I'll do that. thanks

Hi

On Tue, Mar 23, 2021 at 2:28 PM Daniel P. Berrangé <berrange@redhat.com>
wrote:

> On Mon, Mar 22, 2021 at 02:52:34PM +0400, 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 simplify "Edit on Gitlab" links.
>
> s/simplify/simplifies the/
>
>
ok

>
> > Tweak a bit the custom theme to match qemu.org style, use the
> > QEMU logo, and favicon etc.
> >
> > Screenshot:
> >
> https://i.ibb.co/XWwG1bZ/Screenshot-2021-01-20-Welcome-to-QEMU-s-documentation-QEMU-documentation.png
>
> I'd drop this from the commit message unless you're confident
> this link will remain alive indefinitely.
>

No, I'll drop it.


> >
> > Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> > Tested-by: Bin Meng <bmeng.cn@gmail.com>
> > ---
> > v4:
> >  - resend (with Bin T-b, and with minor style fixes)
> >
> >  docs/_templates/editpage.html              |   5 -
> >  docs/conf.py                               |  50 ++++---
> >  docs/devel/_templates/editpage.html        |   5 -
> >  docs/interop/_templates/editpage.html      |   5 -
> >  docs/specs/_templates/editpage.html        |   5 -
> >  docs/sphinx-static/theme_overrides.css     | 161 +++++++++++++++++++++
> >  docs/system/_templates/editpage.html       |   5 -
> >  docs/tools/_templates/editpage.html        |   5 -
> >  docs/user/_templates/editpage.html         |   5 -
> >  tests/docker/dockerfiles/debian10.docker   |   1 +
> >  tests/docker/dockerfiles/fedora.docker     |   1 +
> >  tests/docker/dockerfiles/ubuntu.docker     |   1 +
> >  tests/docker/dockerfiles/ubuntu1804.docker |   1 +
> >  tests/docker/dockerfiles/ubuntu2004.docker |   1 +
> >  14 files changed, 196 insertions(+), 55 deletions(-)
> >  delete mode 100644 docs/_templates/editpage.html
> >  delete mode 100644 docs/devel/_templates/editpage.html
> >  delete mode 100644 docs/interop/_templates/editpage.html
> >  delete mode 100644 docs/specs/_templates/editpage.html
> >  create mode 100644 docs/sphinx-static/theme_overrides.css
> >  delete mode 100644 docs/system/_templates/editpage.html
> >  delete mode 100644 docs/tools/_templates/editpage.html
> >  delete mode 100644 docs/user/_templates/editpage.html
> >
> > diff --git a/docs/_templates/editpage.html
> b/docs/_templates/editpage.html
> > deleted file mode 100644
> > index 4319b0f5ac..0000000000
> > --- a/docs/_templates/editpage.html
> > +++ /dev/null
> > @@ -1,5 +0,0 @@
> > -<div id="editpage">
> > -  <ul>
> > -    <li><a href="
> https://gitlab.com/qemu-project/qemu/-/blob/master/docs/{{pagename}}.rst">Page
> source</a></li>
> > -  </ul>
> > -</div>
> > diff --git a/docs/conf.py b/docs/conf.py
> > index 2ee6111872..17e0319d69 100644
> > --- a/docs/conf.py
> > +++ b/docs/conf.py
> > @@ -151,37 +151,47 @@
> >  # 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 = {
> > -}
> > +if html_theme == 'sphinx_rtd_theme':
> > +    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_css_files = [
> > +    'theme_overrides.css',
> > +]
>
> Does this still have a good result in the case where we fall back
> to alabaster theme ?
>

Yes (I can't see much difference)


> > +
> > +html_context = {
> > +    "display_gitlab": True,
> > +    "gitlab_user": "qemu-project",
> > +    "gitlab_repo": "qemu",
> > +    "gitlab_version": "master",
> > +    "conf_py_path": "/docs/", # Path in the checkout to the docs root
> > +}
> >
> >  # 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',
> > -        'editpage.html',
> > -        'navigation.html',
> > -        'searchbox.html',
> > -    ]
> > -}
>
> Aren't these still needed when we fall back to the alabaster theme ?
>

No difference with the default for me.


> Well the editpage.html can be dropped without real harm, but the
> navigation.html looks pretty important to me.
>
> > +#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.
>
>
>
>
> Regards,
> Daniel
> --
> |: https://berrange.com      -o-
> https://www.flickr.com/photos/dberrange :|
> |: https://libvirt.org         -o-
> https://fstop138.berrange.com :|
> |: https://entangle-photo.org    -o-
> https://www.instagram.com/dberrange :|
>
>
>

-- 
Marc-André Lureau

Hi

On Mon, Mar 22, 2021 at 2:52 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 simplify "Edit on Gitlab" links.
>
> Tweak a bit the custom theme to match qemu.org style, use the
> QEMU logo, and favicon etc.
>
> Screenshot:
>
> https://i.ibb.co/XWwG1bZ/Screenshot-2021-01-20-Welcome-to-QEMU-s-documentation-QEMU-documentation.png


Sorry, this link is outdated now. Here is a more stable one:
https://elmarco.fedorapeople.org/Screenshot_2021-03-22%20Welcome%20to%20QEMU%e2%80%99s%20documentation%20%e2%80%94%20QEMU%20documentation.png


>
> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> Tested-by: Bin Meng <bmeng.cn@gmail.com>
> ---
> v4:
>  - resend (with Bin T-b, and with minor style fixes)
>
>  docs/_templates/editpage.html              |   5 -
>  docs/conf.py                               |  50 ++++---
>  docs/devel/_templates/editpage.html        |   5 -
>  docs/interop/_templates/editpage.html      |   5 -
>  docs/specs/_templates/editpage.html        |   5 -
>  docs/sphinx-static/theme_overrides.css     | 161 +++++++++++++++++++++
>  docs/system/_templates/editpage.html       |   5 -
>  docs/tools/_templates/editpage.html        |   5 -
>  docs/user/_templates/editpage.html         |   5 -
>  tests/docker/dockerfiles/debian10.docker   |   1 +
>  tests/docker/dockerfiles/fedora.docker     |   1 +
>  tests/docker/dockerfiles/ubuntu.docker     |   1 +
>  tests/docker/dockerfiles/ubuntu1804.docker |   1 +
>  tests/docker/dockerfiles/ubuntu2004.docker |   1 +
>  14 files changed, 196 insertions(+), 55 deletions(-)
>  delete mode 100644 docs/_templates/editpage.html
>  delete mode 100644 docs/devel/_templates/editpage.html
>  delete mode 100644 docs/interop/_templates/editpage.html
>  delete mode 100644 docs/specs/_templates/editpage.html
>  create mode 100644 docs/sphinx-static/theme_overrides.css
>  delete mode 100644 docs/system/_templates/editpage.html
>  delete mode 100644 docs/tools/_templates/editpage.html
>  delete mode 100644 docs/user/_templates/editpage.html
>
> diff --git a/docs/_templates/editpage.html b/docs/_templates/editpage.html
> deleted file mode 100644
> index 4319b0f5ac..0000000000
> --- a/docs/_templates/editpage.html
> +++ /dev/null
> @@ -1,5 +0,0 @@
> -<div id="editpage">
> -  <ul>
> -    <li><a href="
> https://gitlab.com/qemu-project/qemu/-/blob/master/docs/{{pagename}}.rst">Page
> source</a></li>
> -  </ul>
> -</div>
> diff --git a/docs/conf.py b/docs/conf.py
> index 2ee6111872..17e0319d69 100644
> --- a/docs/conf.py
> +++ b/docs/conf.py
> @@ -151,37 +151,47 @@
>  # 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 = {
> -}
> +if html_theme == 'sphinx_rtd_theme':
> +    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_css_files = [
> +    'theme_overrides.css',
> +]
> +
> +html_context = {
> +    "display_gitlab": True,
> +    "gitlab_user": "qemu-project",
> +    "gitlab_repo": "qemu",
> +    "gitlab_version": "master",
> +    "conf_py_path": "/docs/", # Path in the checkout to the docs root
> +}
>
>  # 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
> <http://alabaster.readthedocs.io/en/latest/installation.html#sidebars-html_sidebars>
> = {
> -    '**': [
> -        'about.html',
> -        'editpage.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/_templates/editpage.html
> b/docs/devel/_templates/editpage.html
> deleted file mode 100644
> index a86d22bca8..0000000000
> --- a/docs/devel/_templates/editpage.html
> +++ /dev/null
> @@ -1,5 +0,0 @@
> -<div id="editpage">
> -  <ul>
> -    <li><a href="
> https://gitlab.com/qemu-project/qemu/-/blob/master/docs/devel/{{pagename}}.rst">Page
> source</a></li>
> -  </ul>
> -</div>
> diff --git a/docs/interop/_templates/editpage.html
> b/docs/interop/_templates/editpage.html
> deleted file mode 100644
> index 215e562681..0000000000
> --- a/docs/interop/_templates/editpage.html
> +++ /dev/null
> @@ -1,5 +0,0 @@
> -<div id="editpage">
> -  <ul>
> -    <li><a href="
> https://gitlab.com/qemu-project/qemu/-/blob/master/docs/interop/{{pagename}}.rst">Page
> source</a></li>
> -  </ul>
> -</div>
> diff --git a/docs/specs/_templates/editpage.html
> b/docs/specs/_templates/editpage.html
> deleted file mode 100644
> index aaa468aa98..0000000000
> --- a/docs/specs/_templates/editpage.html
> +++ /dev/null
> @@ -1,5 +0,0 @@
> -<div id="editpage">
> -  <ul>
> -    <li><a href="
> https://gitlab.com/qemu-project/qemu/-/blob/master/docs/specs/{{pagename}}.rst">Page
> source</a></li>
> -  </ul>
> -</div>
> diff --git a/docs/sphinx-static/theme_overrides.css
> b/docs/sphinx-static/theme_overrides.css
> new file mode 100644
> index 0000000000..c70ef95128
> --- /dev/null
> +++ b/docs/sphinx-static/theme_overrides.css
> @@ -0,0 +1,161 @@
> +/* -*- 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;
> +}
> +
> +.rst-content dl:not(.docutils) dt {
> +    border-top: none;
> +    border-left: solid 3px #ccc;
> +    background-color: #f0f0f0;
> +    color: black;
> +}
> +
> +.wy-nav-top {
> +    background: #802400;
> +}
> +
> +.wy-side-nav-search input[type="text"] {
> +    border-color: #f60;
> +}
> +
> +.wy-menu-vertical p.caption {
> +    color: white;
> +}
> +
> +.wy-menu-vertical li.current a {
> +    color: #505050;
> +}
> +
> +.wy-menu-vertical li.on a, .wy-menu-vertical li.current > a {
> +    color: #303030;
> +}
> +
> +.fa-gitlab {
> +      box-shadow: 0 4px 8px 0 rgba(0,0,0,0.2), 0 3px 10px 0
> rgba(0,0,0,0.19);
> +      border-radius: 5px;
> +}
> +
> +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/_templates/editpage.html
> b/docs/system/_templates/editpage.html
> deleted file mode 100644
> index 6586b2e257..0000000000
> --- a/docs/system/_templates/editpage.html
> +++ /dev/null
> @@ -1,5 +0,0 @@
> -<div id="editpage">
> -  <ul>
> -    <li><a href="
> https://gitlab.com/qemu-project/qemu/-/blob/master/docs/system/{{pagename}}.rst">Page
> source</a></li>
> -  </ul>
> -</div>
> diff --git a/docs/tools/_templates/editpage.html
> b/docs/tools/_templates/editpage.html
> deleted file mode 100644
> index 2a9c8fc92b..0000000000
> --- a/docs/tools/_templates/editpage.html
> +++ /dev/null
> @@ -1,5 +0,0 @@
> -<div id="editpage">
> -  <ul>
> -    <li><a href="
> https://gitlab.com/qemu-project/qemu/-/blob/master/docs/tools/{{pagename}}.rst">Page
> source</a></li>
> -  </ul>
> -</div>
> diff --git a/docs/user/_templates/editpage.html
> b/docs/user/_templates/editpage.html
> deleted file mode 100644
> index 1f5ee01e60..0000000000
> --- a/docs/user/_templates/editpage.html
> +++ /dev/null
> @@ -1,5 +0,0 @@
> -<div id="editpage">
> -  <ul>
> -    <li><a href="
> https://gitlab.com/qemu-project/qemu/-/blob/master/docs/user/{{pagename}}.rst">Page
> source</a></li>
> -  </ul>
> -</div>
> diff --git a/tests/docker/dockerfiles/debian10.docker
> b/tests/docker/dockerfiles/debian10.docker
> index d034acbd25..63cf835ec5 100644
> --- a/tests/docker/dockerfiles/debian10.docker
> +++ b/tests/docker/dockerfiles/debian10.docker
> @@ -32,6 +32,7 @@ RUN apt update && \
>          psmisc \
>          python3 \
>          python3-sphinx \
> +        python3-sphinx-rtd-theme \
>          $(apt-get -s build-dep --arch-only qemu | egrep ^Inst | fgrep
> '[all]' | cut -d\  -f2)
>
>  ENV FEATURES docs
> diff --git a/tests/docker/dockerfiles/fedora.docker
> b/tests/docker/dockerfiles/fedora.docker
> index 915fdc1845..d8fa16372d 100644
> --- a/tests/docker/dockerfiles/fedora.docker
> +++ b/tests/docker/dockerfiles/fedora.docker
> @@ -92,6 +92,7 @@ ENV PACKAGES \
>      python3-pillow \
>      python3-pip \
>      python3-sphinx \
> +    python3-sphinx_rtd_theme \
>      python3-virtualenv \
>      rdma-core-devel \
>      SDL2-devel \
> diff --git a/tests/docker/dockerfiles/ubuntu.docker
> b/tests/docker/dockerfiles/ubuntu.docker
> index b5ef7a8198..98a527361c 100644
> --- a/tests/docker/dockerfiles/ubuntu.docker
> +++ b/tests/docker/dockerfiles/ubuntu.docker
> @@ -63,6 +63,7 @@ ENV PACKAGES \
>      ninja-build \
>      python3-yaml \
>      python3-sphinx \
> +    python3-sphinx-rtd-theme \
>      sparse \
>      xfslibs-dev
>  RUN apt-get update && \
> diff --git a/tests/docker/dockerfiles/ubuntu1804.docker
> b/tests/docker/dockerfiles/ubuntu1804.docker
> index 9b0a19ba5e..c0d3642507 100644
> --- a/tests/docker/dockerfiles/ubuntu1804.docker
> +++ b/tests/docker/dockerfiles/ubuntu1804.docker
> @@ -48,6 +48,7 @@ ENV PACKAGES \
>      make \
>      python3-yaml \
>      python3-sphinx \
> +    python3-sphinx-rtd-theme \
>      ninja-build \
>      sparse \
>      xfslibs-dev
> diff --git a/tests/docker/dockerfiles/ubuntu2004.docker
> b/tests/docker/dockerfiles/ubuntu2004.docker
> index 9750016e51..f1e0ebad49 100644
> --- a/tests/docker/dockerfiles/ubuntu2004.docker
> +++ b/tests/docker/dockerfiles/ubuntu2004.docker
> @@ -58,6 +58,7 @@ ENV PACKAGES flex bison \
>      python3-pil \
>      python3-pip \
>      python3-sphinx \
> +    python3-sphinx-rtd-theme \
>      python3-venv \
>      python3-yaml \
>      rpm2cpio \
> --
> 2.29.0
>
>

On Mon, Mar 22, 2021 at 2:59 PM Marc-André Lureau <
marcandre.lureau@redhat.com> wrote:

> Hi
>
> On Mon, Mar 22, 2021 at 2:52 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 simplify "Edit on Gitlab" links.
>>
>> Tweak a bit the custom theme to match qemu.org style, use the
>> QEMU logo, and favicon etc.
>>
>> Screenshot:
>>
>> https://i.ibb.co/XWwG1bZ/Screenshot-2021-01-20-Welcome-to-QEMU-s-documentation-QEMU-documentation.png
>
>
> Sorry, this link is outdated now. Here is a more stable one:
>
> https://elmarco.fedorapeople.org/Screenshot_2021-03-22%20Welcome%20to%20QEMU%e2%80%99s%20documentation%20%e2%80%94%20QEMU%20documentation.png
>
>
What about simplifying the various section titles?
https://elmarco.fedorapeople.org/Screenshot_2021-03-22%20Welcome%20to%20QEMU%e2%80%99s%20documentation%20%e2%80%94%20QEMU%20documentation(1).png


>>
>> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
>> Tested-by: Bin Meng <bmeng.cn@gmail.com>
>> ---
>> v4:
>>  - resend (with Bin T-b, and with minor style fixes)
>>
>>  docs/_templates/editpage.html              |   5 -
>>  docs/conf.py                               |  50 ++++---
>>  docs/devel/_templates/editpage.html        |   5 -
>>  docs/interop/_templates/editpage.html      |   5 -
>>  docs/specs/_templates/editpage.html        |   5 -
>>  docs/sphinx-static/theme_overrides.css     | 161 +++++++++++++++++++++
>>  docs/system/_templates/editpage.html       |   5 -
>>  docs/tools/_templates/editpage.html        |   5 -
>>  docs/user/_templates/editpage.html         |   5 -
>>  tests/docker/dockerfiles/debian10.docker   |   1 +
>>  tests/docker/dockerfiles/fedora.docker     |   1 +
>>  tests/docker/dockerfiles/ubuntu.docker     |   1 +
>>  tests/docker/dockerfiles/ubuntu1804.docker |   1 +
>>  tests/docker/dockerfiles/ubuntu2004.docker |   1 +
>>  14 files changed, 196 insertions(+), 55 deletions(-)
>>  delete mode 100644 docs/_templates/editpage.html
>>  delete mode 100644 docs/devel/_templates/editpage.html
>>  delete mode 100644 docs/interop/_templates/editpage.html
>>  delete mode 100644 docs/specs/_templates/editpage.html
>>  create mode 100644 docs/sphinx-static/theme_overrides.css
>>  delete mode 100644 docs/system/_templates/editpage.html
>>  delete mode 100644 docs/tools/_templates/editpage.html
>>  delete mode 100644 docs/user/_templates/editpage.html
>>
>> diff --git a/docs/_templates/editpage.html b/docs/_templates/editpage.html
>> deleted file mode 100644
>> index 4319b0f5ac..0000000000
>> --- a/docs/_templates/editpage.html
>> +++ /dev/null
>> @@ -1,5 +0,0 @@
>> -<div id="editpage">
>> -  <ul>
>> -    <li><a href="
>> https://gitlab.com/qemu-project/qemu/-/blob/master/docs/{{pagename}}.rst">Page
>> source</a></li>
>> -  </ul>
>> -</div>
>> diff --git a/docs/conf.py b/docs/conf.py
>> index 2ee6111872..17e0319d69 100644
>> --- a/docs/conf.py
>> +++ b/docs/conf.py
>> @@ -151,37 +151,47 @@
>>  # 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 = {
>> -}
>> +if html_theme == 'sphinx_rtd_theme':
>> +    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_css_files = [
>> +    'theme_overrides.css',
>> +]
>> +
>> +html_context = {
>> +    "display_gitlab": True,
>> +    "gitlab_user": "qemu-project",
>> +    "gitlab_repo": "qemu",
>> +    "gitlab_version": "master",
>> +    "conf_py_path": "/docs/", # Path in the checkout to the docs root
>> +}
>>
>>  # 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
>> <http://alabaster.readthedocs.io/en/latest/installation.html#sidebars-html_sidebars>
>> = {
>> -    '**': [
>> -        'about.html',
>> -        'editpage.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/_templates/editpage.html
>> b/docs/devel/_templates/editpage.html
>> deleted file mode 100644
>> index a86d22bca8..0000000000
>> --- a/docs/devel/_templates/editpage.html
>> +++ /dev/null
>> @@ -1,5 +0,0 @@
>> -<div id="editpage">
>> -  <ul>
>> -    <li><a href="
>> https://gitlab.com/qemu-project/qemu/-/blob/master/docs/devel/{{pagename}}.rst">Page
>> source</a></li>
>> -  </ul>
>> -</div>
>> diff --git a/docs/interop/_templates/editpage.html
>> b/docs/interop/_templates/editpage.html
>> deleted file mode 100644
>> index 215e562681..0000000000
>> --- a/docs/interop/_templates/editpage.html
>> +++ /dev/null
>> @@ -1,5 +0,0 @@
>> -<div id="editpage">
>> -  <ul>
>> -    <li><a href="
>> https://gitlab.com/qemu-project/qemu/-/blob/master/docs/interop/{{pagename}}.rst">Page
>> source</a></li>
>> -  </ul>
>> -</div>
>> diff --git a/docs/specs/_templates/editpage.html
>> b/docs/specs/_templates/editpage.html
>> deleted file mode 100644
>> index aaa468aa98..0000000000
>> --- a/docs/specs/_templates/editpage.html
>> +++ /dev/null
>> @@ -1,5 +0,0 @@
>> -<div id="editpage">
>> -  <ul>
>> -    <li><a href="
>> https://gitlab.com/qemu-project/qemu/-/blob/master/docs/specs/{{pagename}}.rst">Page
>> source</a></li>
>> -  </ul>
>> -</div>
>> diff --git a/docs/sphinx-static/theme_overrides.css
>> b/docs/sphinx-static/theme_overrides.css
>> new file mode 100644
>> index 0000000000..c70ef95128
>> --- /dev/null
>> +++ b/docs/sphinx-static/theme_overrides.css
>> @@ -0,0 +1,161 @@
>> +/* -*- 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;
>> +}
>> +
>> +.rst-content dl:not(.docutils) dt {
>> +    border-top: none;
>> +    border-left: solid 3px #ccc;
>> +    background-color: #f0f0f0;
>> +    color: black;
>> +}
>> +
>> +.wy-nav-top {
>> +    background: #802400;
>> +}
>> +
>> +.wy-side-nav-search input[type="text"] {
>> +    border-color: #f60;
>> +}
>> +
>> +.wy-menu-vertical p.caption {
>> +    color: white;
>> +}
>> +
>> +.wy-menu-vertical li.current a {
>> +    color: #505050;
>> +}
>> +
>> +.wy-menu-vertical li.on a, .wy-menu-vertical li.current > a {
>> +    color: #303030;
>> +}
>> +
>> +.fa-gitlab {
>> +      box-shadow: 0 4px 8px 0 rgba(0,0,0,0.2), 0 3px 10px 0
>> rgba(0,0,0,0.19);
>> +      border-radius: 5px;
>> +}
>> +
>> +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/_templates/editpage.html
>> b/docs/system/_templates/editpage.html
>> deleted file mode 100644
>> index 6586b2e257..0000000000
>> --- a/docs/system/_templates/editpage.html
>> +++ /dev/null
>> @@ -1,5 +0,0 @@
>> -<div id="editpage">
>> -  <ul>
>> -    <li><a href="
>> https://gitlab.com/qemu-project/qemu/-/blob/master/docs/system/{{pagename}}.rst">Page
>> source</a></li>
>> -  </ul>
>> -</div>
>> diff --git a/docs/tools/_templates/editpage.html
>> b/docs/tools/_templates/editpage.html
>> deleted file mode 100644
>> index 2a9c8fc92b..0000000000
>> --- a/docs/tools/_templates/editpage.html
>> +++ /dev/null
>> @@ -1,5 +0,0 @@
>> -<div id="editpage">
>> -  <ul>
>> -    <li><a href="
>> https://gitlab.com/qemu-project/qemu/-/blob/master/docs/tools/{{pagename}}.rst">Page
>> source</a></li>
>> -  </ul>
>> -</div>
>> diff --git a/docs/user/_templates/editpage.html
>> b/docs/user/_templates/editpage.html
>> deleted file mode 100644
>> index 1f5ee01e60..0000000000
>> --- a/docs/user/_templates/editpage.html
>> +++ /dev/null
>> @@ -1,5 +0,0 @@
>> -<div id="editpage">
>> -  <ul>
>> -    <li><a href="
>> https://gitlab.com/qemu-project/qemu/-/blob/master/docs/user/{{pagename}}.rst">Page
>> source</a></li>
>> -  </ul>
>> -</div>
>> diff --git a/tests/docker/dockerfiles/debian10.docker
>> b/tests/docker/dockerfiles/debian10.docker
>> index d034acbd25..63cf835ec5 100644
>> --- a/tests/docker/dockerfiles/debian10.docker
>> +++ b/tests/docker/dockerfiles/debian10.docker
>> @@ -32,6 +32,7 @@ RUN apt update && \
>>          psmisc \
>>          python3 \
>>          python3-sphinx \
>> +        python3-sphinx-rtd-theme \
>>          $(apt-get -s build-dep --arch-only qemu | egrep ^Inst | fgrep
>> '[all]' | cut -d\  -f2)
>>
>>  ENV FEATURES docs
>> diff --git a/tests/docker/dockerfiles/fedora.docker
>> b/tests/docker/dockerfiles/fedora.docker
>> index 915fdc1845..d8fa16372d 100644
>> --- a/tests/docker/dockerfiles/fedora.docker
>> +++ b/tests/docker/dockerfiles/fedora.docker
>> @@ -92,6 +92,7 @@ ENV PACKAGES \
>>      python3-pillow \
>>      python3-pip \
>>      python3-sphinx \
>> +    python3-sphinx_rtd_theme \
>>      python3-virtualenv \
>>      rdma-core-devel \
>>      SDL2-devel \
>> diff --git a/tests/docker/dockerfiles/ubuntu.docker
>> b/tests/docker/dockerfiles/ubuntu.docker
>> index b5ef7a8198..98a527361c 100644
>> --- a/tests/docker/dockerfiles/ubuntu.docker
>> +++ b/tests/docker/dockerfiles/ubuntu.docker
>> @@ -63,6 +63,7 @@ ENV PACKAGES \
>>      ninja-build \
>>      python3-yaml \
>>      python3-sphinx \
>> +    python3-sphinx-rtd-theme \
>>      sparse \
>>      xfslibs-dev
>>  RUN apt-get update && \
>> diff --git a/tests/docker/dockerfiles/ubuntu1804.docker
>> b/tests/docker/dockerfiles/ubuntu1804.docker
>> index 9b0a19ba5e..c0d3642507 100644
>> --- a/tests/docker/dockerfiles/ubuntu1804.docker
>> +++ b/tests/docker/dockerfiles/ubuntu1804.docker
>> @@ -48,6 +48,7 @@ ENV PACKAGES \
>>      make \
>>      python3-yaml \
>>      python3-sphinx \
>> +    python3-sphinx-rtd-theme \
>>      ninja-build \
>>      sparse \
>>      xfslibs-dev
>> diff --git a/tests/docker/dockerfiles/ubuntu2004.docker
>> b/tests/docker/dockerfiles/ubuntu2004.docker
>> index 9750016e51..f1e0ebad49 100644
>> --- a/tests/docker/dockerfiles/ubuntu2004.docker
>> +++ b/tests/docker/dockerfiles/ubuntu2004.docker
>> @@ -58,6 +58,7 @@ ENV PACKAGES flex bison \
>>      python3-pil \
>>      python3-pip \
>>      python3-sphinx \
>> +    python3-sphinx-rtd-theme \
>>      python3-venv \
>>      python3-yaml \
>>      rpm2cpio \
>> --
>> 2.29.0
>>
>>

On Mon, Mar 22, 2021 at 03:34:23PM +0400, Marc-André Lureau wrote:
> On Mon, Mar 22, 2021 at 2:59 PM Marc-André Lureau <
> marcandre.lureau@redhat.com> wrote:
> 
> > Hi
> >
> > On Mon, Mar 22, 2021 at 2:52 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 simplify "Edit on Gitlab" links.
> >>
> >> Tweak a bit the custom theme to match qemu.org style, use the
> >> QEMU logo, and favicon etc.
> >>
> >> Screenshot:
> >>
> >> https://i.ibb.co/XWwG1bZ/Screenshot-2021-01-20-Welcome-to-QEMU-s-documentation-QEMU-documentation.png
> >
> >
> > Sorry, this link is outdated now. Here is a more stable one:
> >
> > https://elmarco.fedorapeople.org/Screenshot_2021-03-22%20Welcome%20to%20QEMU%e2%80%99s%20documentation%20%e2%80%94%20QEMU%20documentation.png
> >
> >
> What about simplifying the various section titles?
> https://elmarco.fedorapeople.org/Screenshot_2021-03-22%20Welcome%20to%20QEMU%e2%80%99s%20documentation%20%e2%80%94%20QEMU%20documentation(1).png

I think that makes sense, now that we have everything merged
into one doc, and certainly makes the nav look nicer.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|