* [PULL v2 0/1] readthedoc theme patch @ 2021-05-10 13:06 marcandre.lureau 2021-05-10 13:06 ` [PULL v2 1/1] sphinx: adopt kernel readthedoc theme marcandre.lureau 2021-05-12 13:43 ` [PULL v2 0/1] readthedoc theme patch Peter Maydell 0 siblings, 2 replies; 13+ messages in thread From: marcandre.lureau @ 2021-05-10 13:06 UTC (permalink / raw) To: qemu-devel; +Cc: Peter Maydell, Marc-André 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* [PULL v2 1/1] sphinx: adopt kernel readthedoc theme 2021-05-10 13:06 [PULL v2 0/1] readthedoc theme patch marcandre.lureau @ 2021-05-10 13:06 ` marcandre.lureau 2021-05-12 13:43 ` [PULL v2 0/1] readthedoc theme patch Peter Maydell 1 sibling, 0 replies; 13+ messages in thread From: marcandre.lureau @ 2021-05-10 13:06 UTC (permalink / raw) To: qemu-devel; +Cc: Peter Maydell, Marc-André 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 ^ permalink raw reply related [flat|nested] 13+ messages in thread
* Re: [PULL v2 0/1] readthedoc theme patch 2021-05-10 13:06 [PULL v2 0/1] readthedoc theme patch marcandre.lureau 2021-05-10 13:06 ` [PULL v2 1/1] sphinx: adopt kernel readthedoc theme marcandre.lureau @ 2021-05-12 13:43 ` Peter Maydell 2021-05-12 15:17 ` Marc-André Lureau 1 sibling, 1 reply; 13+ messages in thread From: Peter Maydell @ 2021-05-12 13:43 UTC (permalink / raw) To: Marc-André Lureau; +Cc: QEMU Developers 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [PULL v2 0/1] readthedoc theme patch 2021-05-12 13:43 ` [PULL v2 0/1] readthedoc theme patch Peter Maydell @ 2021-05-12 15:17 ` Marc-André Lureau 2021-05-12 15:54 ` Peter Maydell 0 siblings, 1 reply; 13+ messages in thread From: Marc-André Lureau @ 2021-05-12 15:17 UTC (permalink / raw) To: Peter Maydell; +Cc: QEMU Developers [-- 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 --] ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [PULL v2 0/1] readthedoc theme patch 2021-05-12 15:17 ` Marc-André Lureau @ 2021-05-12 15:54 ` Peter Maydell 2021-05-12 16:02 ` Marc-André Lureau 0 siblings, 1 reply; 13+ messages in thread From: Peter Maydell @ 2021-05-12 15:54 UTC (permalink / raw) To: Marc-André Lureau; +Cc: QEMU Developers 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [PULL v2 0/1] readthedoc theme patch 2021-05-12 15:54 ` Peter Maydell @ 2021-05-12 16:02 ` Marc-André Lureau 2021-05-12 16:17 ` Peter Maydell 0 siblings, 1 reply; 13+ messages in thread From: Marc-André Lureau @ 2021-05-12 16:02 UTC (permalink / raw) To: Peter Maydell; +Cc: QEMU Developers [-- 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 --] ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [PULL v2 0/1] readthedoc theme patch 2021-05-12 16:02 ` Marc-André Lureau @ 2021-05-12 16:17 ` Peter Maydell 2021-05-12 19:31 ` Peter Maydell 0 siblings, 1 reply; 13+ messages in thread From: Peter Maydell @ 2021-05-12 16:17 UTC (permalink / raw) To: Marc-André Lureau; +Cc: QEMU Developers 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [PULL v2 0/1] readthedoc theme patch 2021-05-12 16:17 ` Peter Maydell @ 2021-05-12 19:31 ` Peter Maydell 2021-05-13 13:45 ` Peter Maydell 0 siblings, 1 reply; 13+ messages in thread From: Peter Maydell @ 2021-05-12 19:31 UTC (permalink / raw) To: Marc-André Lureau; +Cc: QEMU Developers 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [PULL v2 0/1] readthedoc theme patch 2021-05-12 19:31 ` Peter Maydell @ 2021-05-13 13:45 ` Peter Maydell 2021-05-13 16:03 ` Marc-André Lureau 0 siblings, 1 reply; 13+ messages in thread From: Peter Maydell @ 2021-05-13 13:45 UTC (permalink / raw) To: Marc-André Lureau; +Cc: QEMU Developers 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [PULL v2 0/1] readthedoc theme patch 2021-05-13 13:45 ` Peter Maydell @ 2021-05-13 16:03 ` Marc-André Lureau 2021-05-13 17:17 ` Peter Maydell 0 siblings, 1 reply; 13+ messages in thread From: Marc-André Lureau @ 2021-05-13 16:03 UTC (permalink / raw) To: Peter Maydell; +Cc: QEMU Developers [-- 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 --] ^ permalink raw reply related [flat|nested] 13+ messages in thread
* Re: [PULL v2 0/1] readthedoc theme patch 2021-05-13 16:03 ` Marc-André Lureau @ 2021-05-13 17:17 ` Peter Maydell 2021-05-14 8:00 ` Marc-André Lureau 0 siblings, 1 reply; 13+ messages in thread From: Peter Maydell @ 2021-05-13 17:17 UTC (permalink / raw) To: Marc-André Lureau; +Cc: QEMU Developers 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [PULL v2 0/1] readthedoc theme patch 2021-05-13 17:17 ` Peter Maydell @ 2021-05-14 8:00 ` Marc-André Lureau 2021-05-14 9:10 ` Peter Maydell 0 siblings, 1 reply; 13+ messages in thread From: Marc-André Lureau @ 2021-05-14 8:00 UTC (permalink / raw) To: Peter Maydell; +Cc: QEMU Developers [-- 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 --] ^ permalink raw reply related [flat|nested] 13+ messages in thread
* Re: [PULL v2 0/1] readthedoc theme patch 2021-05-14 8:00 ` Marc-André Lureau @ 2021-05-14 9:10 ` Peter Maydell 0 siblings, 0 replies; 13+ messages in thread From: Peter Maydell @ 2021-05-14 9:10 UTC (permalink / raw) To: Marc-André Lureau; +Cc: QEMU Developers 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
end of thread, other threads:[~2021-05-14 9:11 UTC | newest] Thread overview: 13+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2021-05-10 13:06 [PULL v2 0/1] readthedoc theme patch marcandre.lureau 2021-05-10 13:06 ` [PULL v2 1/1] sphinx: adopt kernel readthedoc theme marcandre.lureau 2021-05-12 13:43 ` [PULL v2 0/1] readthedoc theme patch Peter Maydell 2021-05-12 15:17 ` Marc-André Lureau 2021-05-12 15:54 ` Peter Maydell 2021-05-12 16:02 ` Marc-André Lureau 2021-05-12 16:17 ` Peter Maydell 2021-05-12 19:31 ` Peter Maydell 2021-05-13 13:45 ` Peter Maydell 2021-05-13 16:03 ` Marc-André Lureau 2021-05-13 17:17 ` Peter Maydell 2021-05-14 8:00 ` Marc-André Lureau 2021-05-14 9:10 ` Peter Maydell
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).