[PULL v2 0/1] readthedoc theme patch

[PULL v2 0/1] readthedoc theme patch

[marcandre.lureau]

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

The following changes since commit d90f154867ec0ec22fd719164b88716e8fd48672:

  Merge remote-tracking branch 'remotes/dg-gitlab/tags/ppc-for-6.1-20210504' into staging (2021-05-05 20:29:14 +0100)

are available in the Git repository at:

  git@gitlab.com:marcandre.lureau/qemu.git tags/rtd-pull-request

for you to fetch changes up to f1852f5d7e6fc2ead874261c0388b18898257000:

  sphinx: adopt kernel readthedoc theme (2021-05-10 15:12:09 +0400)

----------------------------------------------------------------
Pull request

----------------------------------------------------------------

Marc-André Lureau (1):
  sphinx: adopt kernel readthedoc theme

 docs/_templates/editpage.html              |   5 -
 docs/conf.py                               |  51 ++++---
 docs/devel/_templates/editpage.html        |   5 -
 docs/interop/_templates/editpage.html      |   5 -
 docs/meson.build                           |   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/alpine.docker     |   1 +
 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 +
 16 files changed, 199 insertions(+), 59 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

-- 
2.29.0

[PULL v2 1/1] 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 simplifies the "Edit on Gitlab" links.

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

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Tested-by: Bin Meng <bmeng.cn@gmail.com>
Message-Id: <20210323115328.4146052-1-marcandre.lureau@redhat.com>
Reviewed-by: John Snow <jsnow@redhat.com>
---
 docs/_templates/editpage.html              |   5 -
 docs/conf.py                               |  51 ++++---
 docs/devel/_templates/editpage.html        |   5 -
 docs/interop/_templates/editpage.html      |   5 -
 docs/meson.build                           |   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/alpine.docker     |   1 +
 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 +
 16 files changed, 199 insertions(+), 59 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..3802b70d62 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -150,38 +150,47 @@
 # 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
+except ImportError:
+    raise ConfigError(
+        'The Sphinx \'sphinx_rtd_theme\' HTML theme was not found.\n'
+    )
+
+html_theme = 'sphinx_rtd_theme'
 
 # 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/meson.build b/docs/meson.build
index f84306ba7e..855e3916e9 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -27,10 +27,9 @@ if sphinx_build.found()
   build_docs = (sphinx_build_test_out.returncode() == 0)
 
   if not build_docs
-    warning('@0@ is either too old or uses too old a Python version'
-            .format(sphinx_build.full_path()))
+    warning('@0@: @1@'.format(sphinx_build.full_path(), sphinx_build_test_out.stderr()))
     if get_option('docs').enabled()
-      error('Install a Python 3 version of python-sphinx')
+      error('Install a Python 3 version of python-sphinx and the readthedoc theme')
     endif
   endif
 endif
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/alpine.docker b/tests/docker/dockerfiles/alpine.docker
index d63a269aef..88d3bbe5f2 100644
--- a/tests/docker/dockerfiles/alpine.docker
+++ b/tests/docker/dockerfiles/alpine.docker
@@ -39,6 +39,7 @@ ENV PACKAGES \
 	pulseaudio-dev \
 	python3 \
 	py3-sphinx \
+	py3-sphinx_rtd_theme \
 	shadow \
 	snappy-dev \
 	spice-dev \
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

Re: [PULL v2 0/1] readthedoc theme patch

[Peter Maydell]

On Mon, 10 May 2021 at 14:06, <marcandre.lureau@redhat.com> wrote:
>
> From: Marc-André Lureau <marcandre.lureau@redhat.com>
>
> The following changes since commit d90f154867ec0ec22fd719164b88716e8fd48672:
>
>   Merge remote-tracking branch 'remotes/dg-gitlab/tags/ppc-for-6.1-20210504' into staging (2021-05-05 20:29:14 +0100)
>
> are available in the Git repository at:
>
>   git@gitlab.com:marcandre.lureau/qemu.git tags/rtd-pull-request
>
> for you to fetch changes up to f1852f5d7e6fc2ead874261c0388b18898257000:
>
>   sphinx: adopt kernel readthedoc theme (2021-05-10 15:12:09 +0400)
>
> ----------------------------------------------------------------
> Pull request
>
> ----------------------------------------------------------------
>
> Marc-André Lureau (1):
>   sphinx: adopt kernel readthedoc theme

NetBSD now complains:

Configuring 60-edk2-x86_64.json using configuration
Program qemu-keymap found: NO
Program sphinx-build found: YES
../docs/meson.build:30: WARNING: /usr/bin/sphinx-build:
Configuration error:
There is a programable error in your configuration file:

Traceback (most recent call last):
  File "conf.py", line 154, in <module>
    import sphinx_rtd_theme
ModuleNotFoundError: No module named 'sphinx_rtd_theme'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/usr/lib/python3/dist-packages/sphinx/config.py", line 157, in __init__
    execfile_(filename, config)
  File "/usr/lib/python3/dist-packages/sphinx/util/pycompat.py", line
150, in execfile_
    exec_(code, _globals)
  File "conf.py", line 157, in <module>
    'The Sphinx \'sphinx_rtd_theme\' HTML theme was not found.\n'
sphinx.errors.ConfigError: The Sphinx 'sphinx_rtd_theme' HTML theme
was not found.



Program python3 found: YES (/usr/bin/python3)
Program diff found: YES
Program dbus-daemon found: YES


as does freebsd and openbsd. Can we get the theme added to the VM
configs for those ?

-- PMM

Re: [PULL v2 0/1] readthedoc theme patch

[Marc-André Lureau]

[-- Attachment #1: Type: text/plain, Size: 2456 bytes --]

Hi

On Wed, May 12, 2021 at 5:47 PM Peter Maydell <peter.maydell@linaro.org>
wrote:

> On Mon, 10 May 2021 at 14:06, <marcandre.lureau@redhat.com> wrote:
> >
> > From: Marc-André Lureau <marcandre.lureau@redhat.com>
> >
> > The following changes since commit
> d90f154867ec0ec22fd719164b88716e8fd48672:
> >
> >   Merge remote-tracking branch
> 'remotes/dg-gitlab/tags/ppc-for-6.1-20210504' into staging (2021-05-05
> 20:29:14 +0100)
> >
> > are available in the Git repository at:
> >
> >   git@gitlab.com:marcandre.lureau/qemu.git tags/rtd-pull-request
> >
> > for you to fetch changes up to f1852f5d7e6fc2ead874261c0388b18898257000:
> >
> >   sphinx: adopt kernel readthedoc theme (2021-05-10 15:12:09 +0400)
> >
> > ----------------------------------------------------------------
> > Pull request
> >
> > ----------------------------------------------------------------
> >
> > Marc-André Lureau (1):
> >   sphinx: adopt kernel readthedoc theme
>
> NetBSD now complains:
>
> Configuring 60-edk2-x86_64.json using configuration
> Program qemu-keymap found: NO
> Program sphinx-build found: YES
> ../docs/meson.build:30: WARNING: /usr/bin/sphinx-build:
> Configuration error:
> There is a programable error in your configuration file:
>
> Traceback (most recent call last):
>   File "conf.py", line 154, in <module>
>     import sphinx_rtd_theme
> ModuleNotFoundError: No module named 'sphinx_rtd_theme'
>
> During handling of the above exception, another exception occurred:
>
> Traceback (most recent call last):
>   File "/usr/lib/python3/dist-packages/sphinx/config.py", line 157, in
> __init__
>     execfile_(filename, config)
>   File "/usr/lib/python3/dist-packages/sphinx/util/pycompat.py", line
> 150, in execfile_
>     exec_(code, _globals)
>   File "conf.py", line 157, in <module>
>     'The Sphinx \'sphinx_rtd_theme\' HTML theme was not found.\n'
> sphinx.errors.ConfigError: The Sphinx 'sphinx_rtd_theme' HTML theme
> was not found.
>
>
>
> Program python3 found: YES (/usr/bin/python3)
> Program diff found: YES
> Program dbus-daemon found: YES
>
>
> as does freebsd and openbsd. Can we get the theme added to the VM
> configs for those ?
>
>

What is used for the BSD configs? If it's tests/vm, I don't see readthedoc
being installed there, and vm-build-* should work (at least some work for
me, freebsd fails with ssh issue here)

-- 
Marc-André Lureau

[-- Attachment #2: Type: text/html, Size: 3296 bytes --]

Re: [PULL v2 0/1] readthedoc theme patch

[Peter Maydell]

On Wed, 12 May 2021 at 16:17, Marc-André Lureau
<marcandre.lureau@gmail.com> wrote:
>
> Hi
>
> On Wed, May 12, 2021 at 5:47 PM Peter Maydell <peter.maydell@linaro.org> wrote:
>>
>> On Mon, 10 May 2021 at 14:06, <marcandre.lureau@redhat.com> wrote:
>> >
>> > From: Marc-André Lureau <marcandre.lureau@redhat.com>
>> >
>> > The following changes since commit d90f154867ec0ec22fd719164b88716e8fd48672:
>> >
>> >   Merge remote-tracking branch 'remotes/dg-gitlab/tags/ppc-for-6.1-20210504' into staging (2021-05-05 20:29:14 +0100)
>> >
>> > are available in the Git repository at:
>> >
>> >   git@gitlab.com:marcandre.lureau/qemu.git tags/rtd-pull-request
>> >
>> > for you to fetch changes up to f1852f5d7e6fc2ead874261c0388b18898257000:
>> >
>> >   sphinx: adopt kernel readthedoc theme (2021-05-10 15:12:09 +0400)
>> >
>> > ----------------------------------------------------------------
>> > Pull request
>> >
>> > ----------------------------------------------------------------
>> >
>> > Marc-André Lureau (1):
>> >   sphinx: adopt kernel readthedoc theme
>>
>> NetBSD now complains:
>>
>> Configuring 60-edk2-x86_64.json using configuration
>> Program qemu-keymap found: NO
>> Program sphinx-build found: YES
>> ../docs/meson.build:30: WARNING: /usr/bin/sphinx-build:
>> Configuration error:
>> There is a programable error in your configuration file:
>>
>> Traceback (most recent call last):
>>   File "conf.py", line 154, in <module>
>>     import sphinx_rtd_theme
>> ModuleNotFoundError: No module named 'sphinx_rtd_theme'
>>
>> During handling of the above exception, another exception occurred:
>>
>> Traceback (most recent call last):
>>   File "/usr/lib/python3/dist-packages/sphinx/config.py", line 157, in __init__
>>     execfile_(filename, config)
>>   File "/usr/lib/python3/dist-packages/sphinx/util/pycompat.py", line
>> 150, in execfile_
>>     exec_(code, _globals)
>>   File "conf.py", line 157, in <module>
>>     'The Sphinx \'sphinx_rtd_theme\' HTML theme was not found.\n'
>> sphinx.errors.ConfigError: The Sphinx 'sphinx_rtd_theme' HTML theme
>> was not found.
>>
>>
>>
>> Program python3 found: YES (/usr/bin/python3)
>> Program diff found: YES
>> Program dbus-daemon found: YES
>>
>>
>> as does freebsd and openbsd. Can we get the theme added to the VM
>> configs for those ?

> What is used for the BSD configs? If it's tests/vm, I don't see readthedoc being installed there, and vm-build-* should work (at least some work for me, freebsd fails with ssh issue here)

It's tests/vm.  The build doesn't fail, but the printing of the WARNING
is caught by my wrapper scripts (which grep for various warning/error
words to catch issues which don't trigger complete build failures).
Adding the theme to the configs would mean that we can continue to
test docs builds on those platforms.

thanks
-- PMM

Re: [PULL v2 0/1] readthedoc theme patch

[Marc-André Lureau]

[-- Attachment #1: Type: text/plain, Size: 3259 bytes --]

Hi

On Wed, May 12, 2021 at 7:56 PM Peter Maydell <peter.maydell@linaro.org>
wrote:

> On Wed, 12 May 2021 at 16:17, Marc-André Lureau
> <marcandre.lureau@gmail.com> wrote:
> >
> > Hi
> >
> > On Wed, May 12, 2021 at 5:47 PM Peter Maydell <peter.maydell@linaro.org>
> wrote:
> >>
> >> On Mon, 10 May 2021 at 14:06, <marcandre.lureau@redhat.com> wrote:
> >> >
> >> > From: Marc-André Lureau <marcandre.lureau@redhat.com>
> >> >
> >> > The following changes since commit
> d90f154867ec0ec22fd719164b88716e8fd48672:
> >> >
> >> >   Merge remote-tracking branch
> 'remotes/dg-gitlab/tags/ppc-for-6.1-20210504' into staging (2021-05-05
> 20:29:14 +0100)
> >> >
> >> > are available in the Git repository at:
> >> >
> >> >   git@gitlab.com:marcandre.lureau/qemu.git tags/rtd-pull-request
> >> >
> >> > for you to fetch changes up to
> f1852f5d7e6fc2ead874261c0388b18898257000:
> >> >
> >> >   sphinx: adopt kernel readthedoc theme (2021-05-10 15:12:09 +0400)
> >> >
> >> > ----------------------------------------------------------------
> >> > Pull request
> >> >
> >> > ----------------------------------------------------------------
> >> >
> >> > Marc-André Lureau (1):
> >> >   sphinx: adopt kernel readthedoc theme
> >>
> >> NetBSD now complains:
> >>
> >> Configuring 60-edk2-x86_64.json using configuration
> >> Program qemu-keymap found: NO
> >> Program sphinx-build found: YES
> >> ../docs/meson.build:30: WARNING: /usr/bin/sphinx-build:
> >> Configuration error:
> >> There is a programable error in your configuration file:
> >>
> >> Traceback (most recent call last):
> >>   File "conf.py", line 154, in <module>
> >>     import sphinx_rtd_theme
> >> ModuleNotFoundError: No module named 'sphinx_rtd_theme'
> >>
> >> During handling of the above exception, another exception occurred:
> >>
> >> Traceback (most recent call last):
> >>   File "/usr/lib/python3/dist-packages/sphinx/config.py", line 157, in
> __init__
> >>     execfile_(filename, config)
> >>   File "/usr/lib/python3/dist-packages/sphinx/util/pycompat.py", line
> >> 150, in execfile_
> >>     exec_(code, _globals)
> >>   File "conf.py", line 157, in <module>
> >>     'The Sphinx \'sphinx_rtd_theme\' HTML theme was not found.\n'
> >> sphinx.errors.ConfigError: The Sphinx 'sphinx_rtd_theme' HTML theme
> >> was not found.
> >>
> >>
> >>
> >> Program python3 found: YES (/usr/bin/python3)
> >> Program diff found: YES
> >> Program dbus-daemon found: YES
> >>
> >>
> >> as does freebsd and openbsd. Can we get the theme added to the VM
> >> configs for those ?
>
> > What is used for the BSD configs? If it's tests/vm, I don't see
> readthedoc being installed there, and vm-build-* should work (at least some
> work for me, freebsd fails with ssh issue here)
>
> It's tests/vm.  The build doesn't fail, but the printing of the WARNING
> is caught by my wrapper scripts (which grep for various warning/error
> words to catch issues which don't trigger complete build failures).
> Adding the theme to the configs would mean that we can continue to
> test docs builds on those platforms.
>

Didn't you install readthedoc manually there? I don't see those warnings.


-- 
Marc-André Lureau

[-- Attachment #2: Type: text/html, Size: 4654 bytes --]

Re: [PULL v2 0/1] readthedoc theme patch

[Peter Maydell]

On Wed, 12 May 2021 at 17:02, Marc-André Lureau
<marcandre.lureau@gmail.com> wrote:
> On Wed, May 12, 2021 at 7:56 PM Peter Maydell <peter.maydell@linaro.org> wrote:
>> >> NetBSD now complains:
>> >>
>> >> Configuring 60-edk2-x86_64.json using configuration
>> >> Program qemu-keymap found: NO
>> >> Program sphinx-build found: YES
>> >> ../docs/meson.build:30: WARNING: /usr/bin/sphinx-build:
>> >> Configuration error:
>> >> There is a programable error in your configuration file:
>> >>
>> >> Traceback (most recent call last):
>> >>   File "conf.py", line 154, in <module>
>> >>     import sphinx_rtd_theme
>> >> ModuleNotFoundError: No module named 'sphinx_rtd_theme'
>> >>
>> >> During handling of the above exception, another exception occurred:
>> >>
>> >> Traceback (most recent call last):
>> >>   File "/usr/lib/python3/dist-packages/sphinx/config.py", line 157, in __init__
>> >>     execfile_(filename, config)
>> >>   File "/usr/lib/python3/dist-packages/sphinx/util/pycompat.py", line
>> >> 150, in execfile_
>> >>     exec_(code, _globals)
>> >>   File "conf.py", line 157, in <module>
>> >>     'The Sphinx \'sphinx_rtd_theme\' HTML theme was not found.\n'
>> >> sphinx.errors.ConfigError: The Sphinx 'sphinx_rtd_theme' HTML theme
>> >> was not found.
>> >>
>> >>
>> >>
>> >> Program python3 found: YES (/usr/bin/python3)
>> >> Program diff found: YES
>> >> Program dbus-daemon found: YES
>> >>
>> >>
>> >> as does freebsd and openbsd. Can we get the theme added to the VM
>> >> configs for those ?
>>
>> > What is used for the BSD configs? If it's tests/vm, I don't see readthedoc being installed there, and vm-build-* should work (at least some work for me, freebsd fails with ssh issue here)
>>
>> It's tests/vm.  The build doesn't fail, but the printing of the WARNING
>> is caught by my wrapper scripts (which grep for various warning/error
>> words to catch issues which don't trigger complete build failures).
>> Adding the theme to the configs would mean that we can continue to
>> test docs builds on those platforms.
>
>
> Didn't you install readthedoc manually there? I don't see those warnings.

No, I don't install anything manually on the BSD VM setups -- I just
use the tests/vm makefile magic to run a build-and-test.

thanks
-- PMM

Re: [PULL v2 0/1] readthedoc theme patch

[Peter Maydell]

On Wed, 12 May 2021 at 17:17, Peter Maydell <peter.maydell@linaro.org> wrote:
>
> On Wed, 12 May 2021 at 17:02, Marc-André Lureau
> <marcandre.lureau@gmail.com> wrote:
> > On Wed, May 12, 2021 at 7:56 PM Peter Maydell <peter.maydell@linaro.org> wrote:
> >> >> NetBSD now complains:
> >> >>
> >> >> Configuring 60-edk2-x86_64.json using configuration
> >> >> Program qemu-keymap found: NO
> >> >> Program sphinx-build found: YES
> >> >> ../docs/meson.build:30: WARNING: /usr/bin/sphinx-build:
> >> >> Configuration error:
> >> >> There is a programable error in your configuration file:
> >> >>

> >
> > Didn't you install readthedoc manually there? I don't see those warnings.
>
> No, I don't install anything manually on the BSD VM setups -- I just
> use the tests/vm makefile magic to run a build-and-test.

I've figured out what was going on here, and it was my mistake;
I didn't look at the logs closely enough. When my scripts run
'make vm-build-netbsd' or whatever, this can trigger a configure
run in the host, which is what is producing these warnings.
The host makefile then goes on to launch the BSD VM and the
inner configure run inside the VM is fine (as you note it doesn't
have sphinx installed, so no docs are built.)

I should be able to deal with this by installing the rtd theme on
the host. I'll retry merging the pullreq.

thanks
-- PMM

Re: [PULL v2 0/1] readthedoc theme patch

[Peter Maydell]

On Wed, 12 May 2021 at 20:31, Peter Maydell <peter.maydell@linaro.org> wrote:
> I should be able to deal with this by installing the rtd theme on
> the host. I'll retry merging the pullreq.

On try 2 I find that some of my machines warn:

Program qemu-keymap found: NO
Program sphinx-build found: YES
../../docs/meson.build:30: WARNING: /usr/bin/sphinx-build:
Theme error:
unsupported theme option 'style_nav_header_background' given

Program python3 found: YES (/usr/bin/python3)
Program diff found: YES

It looks like this is because it's trying to use an option
that's only present in newer versions of the theme. (Ubuntu
bionic has version 0.2.4 of the rtd theme.)

Is it possible to either avoid or conditionalize the use of
this config setting?

thanks
-- PMM

Re: [PULL v2 0/1] readthedoc theme patch

[Marc-André Lureau]

[-- Attachment #1: Type: text/plain, Size: 1861 bytes --]

Hi

On Thu, May 13, 2021 at 5:45 PM Peter Maydell <peter.maydell@linaro.org>
wrote:

> On Wed, 12 May 2021 at 20:31, Peter Maydell <peter.maydell@linaro.org>
> wrote:
> > I should be able to deal with this by installing the rtd theme on
> > the host. I'll retry merging the pullreq.
>
> On try 2 I find that some of my machines warn:
>
> Program qemu-keymap found: NO
> Program sphinx-build found: YES
> ../../docs/meson.build:30: WARNING: /usr/bin/sphinx-build:
> Theme error:
> unsupported theme option 'style_nav_header_background' given
>
> Program python3 found: YES (/usr/bin/python3)
> Program diff found: YES
>
> It looks like this is because it's trying to use an option
> that's only present in newer versions of the theme. (Ubuntu
> bionic has version 0.2.4 of the rtd theme.)
>
> Is it possible to either avoid or conditionalize the use of
> this config setting?
>
>
This should work, can you check?:

diff --git a/docs/conf.py b/docs/conf.py
index 3802b70d62..9e3d7cee0e 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -29,6 +29,7 @@
 import os
 import sys
 import sphinx
+from packaging.version import parse as parse_version
 from sphinx.errors import ConfigError

 # Make Sphinx fail cleanly if using an old Python, rather than obscurely
@@ -162,7 +163,7 @@
 # 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.
-if html_theme == 'sphinx_rtd_theme':
+if parse_version(sphinx_rtd_theme.__version__) >= parse_version('0.4.3'):
     html_theme_options = {
         "style_nav_header_background": "#802400",
     }

However, we agreed before to not have support fallbacks for missing deps.
Perhaps we should require rtd >= 0.4.3 instead?

thanks again!

-- 
Marc-André Lureau

[-- Attachment #2: Type: text/html, Size: 2690 bytes --]

Re: [PULL v2 0/1] readthedoc theme patch

[Peter Maydell]

On Thu, 13 May 2021 at 17:03, Marc-André Lureau
<marcandre.lureau@gmail.com> wrote:
> This should work, can you check?:
>
> diff --git a/docs/conf.py b/docs/conf.py
> index 3802b70d62..9e3d7cee0e 100644
> --- a/docs/conf.py
> +++ b/docs/conf.py
> @@ -29,6 +29,7 @@
>  import os
>  import sys
>  import sphinx
> +from packaging.version import parse as parse_version
>  from sphinx.errors import ConfigError
>
>  # Make Sphinx fail cleanly if using an old Python, rather than obscurely
> @@ -162,7 +163,7 @@
>  # 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.
> -if html_theme == 'sphinx_rtd_theme':
> +if parse_version(sphinx_rtd_theme.__version__) >= parse_version('0.4.3'):
>      html_theme_options = {
>          "style_nav_header_background": "#802400",
>      }

This fails:

../../docs/meson.build:30: WARNING: /usr/bin/sphinx-build:
Configuration error:
There is a programable error in your configuration file:

Traceback (most recent call last):
  File "/usr/lib/python3/dist-packages/sphinx/config.py", line 157, in __init__
    execfile_(filename, config)
  File "/usr/lib/python3/dist-packages/sphinx/util/pycompat.py", line
150, in execfile_
    exec_(code, _globals)
  File "conf.py", line 32, in <module>
    from packaging.version import parse as parse_version
ModuleNotFoundError: No module named 'packaging'




> However, we agreed before to not have support fallbacks for missing deps. Perhaps we should require rtd >= 0.4.3 instead?

That would prevent the docs from building on too many platforms,
I think. 0.4.3 was only released upstream in Feb 2019.

thanks
-- PMM

Re: [PULL v2 0/1] readthedoc theme patch

[Marc-André Lureau]

[-- Attachment #1: Type: text/plain, Size: 2917 bytes --]

Hi

On Thu, May 13, 2021 at 9:17 PM Peter Maydell <peter.maydell@linaro.org>
wrote:

> On Thu, 13 May 2021 at 17:03, Marc-André Lureau
> <marcandre.lureau@gmail.com> wrote:
> > This should work, can you check?:
> >
> > diff --git a/docs/conf.py b/docs/conf.py
> > index 3802b70d62..9e3d7cee0e 100644
> > --- a/docs/conf.py
> > +++ b/docs/conf.py
> > @@ -29,6 +29,7 @@
> >  import os
> >  import sys
> >  import sphinx
> > +from packaging.version import parse as parse_version
> >  from sphinx.errors import ConfigError
> >
> >  # Make Sphinx fail cleanly if using an old Python, rather than obscurely
> > @@ -162,7 +163,7 @@
> >  # 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.
> > -if html_theme == 'sphinx_rtd_theme':
> > +if parse_version(sphinx_rtd_theme.__version__) >=
> parse_version('0.4.3'):
> >      html_theme_options = {
> >          "style_nav_header_background": "#802400",
> >      }
>
> This fails:
>
> ../../docs/meson.build:30: WARNING: /usr/bin/sphinx-build:
> Configuration error:
> There is a programable error in your configuration file:
>
> Traceback (most recent call last):
>   File "/usr/lib/python3/dist-packages/sphinx/config.py", line 157, in
> __init__
>     execfile_(filename, config)
>   File "/usr/lib/python3/dist-packages/sphinx/util/pycompat.py", line
> 150, in execfile_
>     exec_(code, _globals)
>   File "conf.py", line 32, in <module>
>     from packaging.version import parse as parse_version
> ModuleNotFoundError: No module named 'packaging'
>
>
>
According to SO (
https://stackoverflow.com/questions/11887762/how-do-i-compare-version-numbers-in-python)
there is a second built-in option to compare versions.

diff --git a/docs/conf.py b/docs/conf.py
index 3802b70d62..00cf66ab54 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -29,6 +29,7 @@
 import os
 import sys
 import sphinx
+from distutils.version import LooseVersion
 from sphinx.errors import ConfigError

 # Make Sphinx fail cleanly if using an old Python, rather than obscurely
@@ -162,7 +163,7 @@
 # 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.
-if html_theme == 'sphinx_rtd_theme':
+if LooseVersion(sphinx_rtd_theme.__version__) >= LooseVersion("0.4.3"):
     html_theme_options = {
         "style_nav_header_background": "#802400",
     }


Let me know if you want a new PR.


>
> > However, we agreed before to not have support fallbacks for missing
> deps. Perhaps we should require rtd >= 0.4.3 instead?
>
> That would prevent the docs from building on too many platforms,
> I think. 0.4.3 was only released upstream in Feb 2019.
>
>
Ok

-- 
Marc-André Lureau

[-- Attachment #2: Type: text/html, Size: 4093 bytes --]

Re: [PULL v2 0/1] readthedoc theme patch

[Peter Maydell]

On Fri, 14 May 2021 at 09:01, Marc-André Lureau
<marcandre.lureau@gmail.com> wrote:
>
> Let me know if you want a new PR.

If you could send a new PR that would be the easiest for me.

thanks
-- PMM