| Message ID | 20210120102556.125012-1-marcandre.lureau@redhat.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [v3] sphinx: adopt kernel readthedoc theme | expand |
Patchew URL: https://patchew.org/QEMU/20210120102556.125012-1-marcandre.lureau@redhat.com/
Hi,
This series seems to have some coding style problems. See output below for
more information:
Type: series
Message-id: 20210120102556.125012-1-marcandre.lureau@redhat.com
Subject: [PATCH v3] sphinx: adopt kernel readthedoc theme
=== TEST SCRIPT BEGIN ===
#!/bin/bash
git rev-parse base > /dev/null || exit 0
git config --local diff.renamelimit 0
git config --local diff.renames True
git config --local diff.algorithm histogram
./scripts/checkpatch.pl --mailback base..
=== TEST SCRIPT END ===
Updating 3c8cf5a9c21ff8782164d1def7f44bd888713384
From https://github.com/patchew-project/qemu
- [tag update] patchew/20201207172030.251905-1-stefanha@redhat.com -> patchew/20201207172030.251905-1-stefanha@redhat.com
- [tag update] patchew/20210120060255.558535-1-alxndr@bu.edu -> patchew/20210120060255.558535-1-alxndr@bu.edu
* [new tag] patchew/20210120102556.125012-1-marcandre.lureau@redhat.com -> patchew/20210120102556.125012-1-marcandre.lureau@redhat.com
- [tag update] patchew/96eb4f94e6381082ec0188ad180f60f19f2583fc.1611059652.git.mprivozn@redhat.com -> patchew/96eb4f94e6381082ec0188ad180f60f19f2583fc.1611059652.git.mprivozn@redhat.com
Switched to a new branch 'test'
d8ba252 sphinx: adopt kernel readthedoc theme
=== OUTPUT BEGIN ===
WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
#42:
deleted file mode 100644
ERROR: line over 90 characters
#64: FILE: docs/conf.py:158:
+ 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')
ERROR: trailing whitespace
#98: FILE: docs/conf.py:183:
+ "gitlab_user": "qemu-project", $
total: 2 errors, 1 warnings, 260 lines checked
Commit d8ba25269700 (sphinx: adopt kernel readthedoc theme) has style problems, please review. If any of these errors
are false positives report them to the maintainer, see
CHECKPATCH in MAINTAINERS.
=== OUTPUT END ===
Test command exited with code: 1
The full log is available at
http://patchew.org/logs/20210120102556.125012-1-marcandre.lureau@redhat.com/testing.checkpatch/?type=message.
---
Email generated automatically by Patchew [https://patchew.org/].
Please send your feedback to patchew-devel@redhat.com
On Wed, Jan 20, 2021 at 6:26 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 > > Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> > --- > docs/_templates/editpage.html | 5 - > docs/conf.py | 47 +++--- > 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, 193 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..5ee577750b 100644 > --- a/docs/conf.py > +++ b/docs/conf.py > @@ -151,37 +151,44 @@ with open(os.path.join(qemu_docdir, 'defs.rst.inc')) as f: > # 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", Still, there is a trailing space here > + "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. Tested-by: Bin Meng <bmeng.cn@gmail.com>
On 1/20/21 5:25 AM, 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 > > Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> > --- > docs/_templates/editpage.html | 5 - > docs/conf.py | 47 +++--- > 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, 193 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..5ee577750b 100644 > --- a/docs/conf.py > +++ b/docs/conf.py > @@ -151,37 +151,44 @@ with open(os.path.join(qemu_docdir, 'defs.rst.inc')) as f: > # 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", > + } > + This needs a default for html_theme_options so that if sphinx_rtd_theme isn't present, the build doesn't break when using the fallback to alabaster; I'm seeing: Traceback (most recent call last): File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 361, in eval_config_file execfile_(filename, namespace) File "/usr/lib/python3.8/site-packages/sphinx/util/pycompat.py", line 81, in execfile_ exec(code, _globals) File "/home/jsnow/src/qemu/docs/user/conf.py", line 15, in <module> html_theme_options['description'] = u'User Mode Emulation User''s Guide' NameError: name 'html_theme_options' is not defined etc. > +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', > +] > + We probably don't want this to apply to the alabaster fallback, do we? (OTOH: It is a fallback, so maybe who cares? Maybe it's not worth the complexity to try and support both themes.) > +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 > +} > Could be a separate patch, MAYBE, explaining that this is to enable the "Edit on gitlab!" links, which I do think are very cool and useful. > # 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 = {} > More stuff that damages the alabaster fallback. Putting it back, however, causes another problem: > # 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 If you keep html_sidebars, this fails to build because it's gone now. If enough distros have the right theme package, I'm leaning towards just chopping out the fallback entirely instead of bothering with the messy pain of doing both. --js > 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 9d42b5a4b8..957ecdcd50 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 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 0b5053f2d0..db249d1506 100644 > --- a/tests/docker/dockerfiles/fedora.docker > +++ b/tests/docker/dockerfiles/fedora.docker > @@ -89,6 +89,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 ae889d8482..33c19e1762 100644 > --- a/tests/docker/dockerfiles/ubuntu2004.docker > +++ b/tests/docker/dockerfiles/ubuntu2004.docker > @@ -55,6 +55,7 @@ ENV PACKAGES flex bison \ > python3-pil \ > python3-pip \ > python3-sphinx \ > + python3-sphinx-rtd-theme \ > python3-venv \ > python3-yaml \ > rpm2cpio \ >
Hi On Fri, Jan 22, 2021 at 12:59 AM John Snow <jsnow@redhat.com> wrote: > > On 1/20/21 5:25 AM, 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 > > > > Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> > > --- > > docs/_templates/editpage.html | 5 - > > docs/conf.py | 47 +++--- > > 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, 193 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..5ee577750b 100644 > > --- a/docs/conf.py > > +++ b/docs/conf.py > > @@ -151,37 +151,44 @@ with open(os.path.join(qemu_docdir, 'defs.rst.inc')) as f: > > # 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", > > + } > > + > > This needs a default for html_theme_options so that if sphinx_rtd_theme > isn't present, the build doesn't break when using the fallback to > alabaster; I'm seeing: > > Traceback (most recent call last): > File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 361, > in eval_config_file > execfile_(filename, namespace) > File "/usr/lib/python3.8/site-packages/sphinx/util/pycompat.py", line > 81, in execfile_ > exec(code, _globals) > File "/home/jsnow/src/qemu/docs/user/conf.py", line 15, in <module> > html_theme_options['description'] = u'User Mode Emulation User''s > Guide' > NameError: name 'html_theme_options' is not defined > Ok, I don't get that error with sphinx 3.2.1 on fc33... > etc. > > > +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', > > +] > > + > > We probably don't want this to apply to the alabaster fallback, do we? > > (OTOH: It is a fallback, so maybe who cares? Maybe it's not worth the > complexity to try and support both themes.) I agree, they seem significantly different to handle, not sure it's worth the trouble. > > > +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 > > +} > > > > Could be a separate patch, MAYBE, explaining that this is to enable the > "Edit on gitlab!" links, which I do think are very cool and useful. I am not sure it's worth a different patch, because it is simple enough and replaces the pre-existing "Page source" link. > > > # 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 = {} > > > > More stuff that damages the alabaster fallback. Putting it back, > however, causes another problem arg > > > # 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 > > If you keep html_sidebars, this fails to build because it's gone now. If > enough distros have the right theme package, I'm leaning towards just > chopping out the fallback entirely instead of bothering with the messy > pain of doing both. Peter, do you have an opinion about whether we should support a fallback/default theme? Given that RTD is the kernel theme, it seems widely available: https://repology.org/project/python:sphinx-rtd-theme/versions. I can update the patch to check if the sphinx_rtd_theme module is present, and error during configure time. Thanks > > --js > > > 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 9d42b5a4b8..957ecdcd50 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 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 0b5053f2d0..db249d1506 100644 > > --- a/tests/docker/dockerfiles/fedora.docker > > +++ b/tests/docker/dockerfiles/fedora.docker > > @@ -89,6 +89,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 ae889d8482..33c19e1762 100644 > > --- a/tests/docker/dockerfiles/ubuntu2004.docker > > +++ b/tests/docker/dockerfiles/ubuntu2004.docker > > @@ -55,6 +55,7 @@ ENV PACKAGES flex bison \ > > python3-pil \ > > python3-pip \ > > python3-sphinx \ > > + python3-sphinx-rtd-theme \ > > python3-venv \ > > python3-yaml \ > > rpm2cpio \ > > > >
On 1/24/21 1:19 PM, Marc-André Lureau wrote: > Hi > > On Fri, Jan 22, 2021 at 12:59 AM John Snow <jsnow@redhat.com> wrote: >> >> On 1/20/21 5:25 AM, 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 >>> >>> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> >>> --- >>> docs/_templates/editpage.html | 5 - >>> docs/conf.py | 47 +++--- >>> 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, 193 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..5ee577750b 100644 >>> --- a/docs/conf.py >>> +++ b/docs/conf.py >>> @@ -151,37 +151,44 @@ with open(os.path.join(qemu_docdir, 'defs.rst.inc')) as f: >>> # 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", >>> + } >>> + >> >> This needs a default for html_theme_options so that if sphinx_rtd_theme >> isn't present, the build doesn't break when using the fallback to >> alabaster; I'm seeing: >> >> Traceback (most recent call last): >> File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 361, >> in eval_config_file >> execfile_(filename, namespace) >> File "/usr/lib/python3.8/site-packages/sphinx/util/pycompat.py", line >> 81, in execfile_ >> exec(code, _globals) >> File "/home/jsnow/src/qemu/docs/user/conf.py", line 15, in <module> >> html_theme_options['description'] = u'User Mode Emulation User''s >> Guide' >> NameError: name 'html_theme_options' is not defined >> > > Ok, I don't get that error with sphinx 3.2.1 on fc33... > Just in case it helps you: - FC33 - Sphinx 3.4.3 - alabaster 0.7.12 - Python 3.9.1 (3.9.1-1.fc33) Hopefully we can just switch over to RTD theme and ignore the fallback, but you'll probably need to come up with a test matrix for sphinx versions and RTD theme versions and ensure that it works on our supported distro list. Variables: - Python versions (3.6 through 3.9) - Sphinx versions (?? through 3.4.3) - sphinx-rtd-theme vesrions (?? through 0.5.1)
Hi On Mon, Jan 25, 2021 at 8:47 PM John Snow <jsnow@redhat.com> wrote: > > On 1/24/21 1:19 PM, Marc-André Lureau wrote: > > Hi > > > > On Fri, Jan 22, 2021 at 12:59 AM John Snow <jsnow@redhat.com> wrote: > >> > >> On 1/20/21 5:25 AM, 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 > >>> > >>> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> > >>> --- > >>> docs/_templates/editpage.html | 5 - > >>> docs/conf.py | 47 +++--- > >>> 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, 193 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..5ee577750b 100644 > >>> --- a/docs/conf.py > >>> +++ b/docs/conf.py > >>> @@ -151,37 +151,44 @@ with open(os.path.join(qemu_docdir, 'defs.rst.inc')) as f: > >>> # 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", > >>> + } > >>> + > >> > >> This needs a default for html_theme_options so that if sphinx_rtd_theme > >> isn't present, the build doesn't break when using the fallback to > >> alabaster; I'm seeing: > >> > >> Traceback (most recent call last): > >> File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 361, > >> in eval_config_file > >> execfile_(filename, namespace) > >> File "/usr/lib/python3.8/site-packages/sphinx/util/pycompat.py", line > >> 81, in execfile_ > >> exec(code, _globals) > >> File "/home/jsnow/src/qemu/docs/user/conf.py", line 15, in <module> > >> html_theme_options['description'] = u'User Mode Emulation User''s > >> Guide' > >> NameError: name 'html_theme_options' is not defined > >> > > > > Ok, I don't get that error with sphinx 3.2.1 on fc33... > > > > Just in case it helps you: > > - FC33 > - Sphinx 3.4.3 > - alabaster 0.7.12 > - Python 3.9.1 (3.9.1-1.fc33) > > Hopefully we can just switch over to RTD theme and ignore the fallback, > but you'll probably need to come up with a test matrix for sphinx > versions and RTD theme versions and ensure that it works on our > supported distro list. > > Variables: > - Python versions (3.6 through 3.9) > - Sphinx versions (?? through 3.4.3) > - sphinx-rtd-theme vesrions (?? through 0.5.1) Well it depends if we consider the sphinx documentation as a first-class product that must build on all the systems we support. When sphinx dependency was added, I don't think we did a thorough check on where it was available and ensuring it builds properly on all those systems. It's a bit unfair to ask that now just for the rtd-theme. That patch already checks debian/fedora/ubuntu (all the dockerfiles where python-sphinx was installed already) (quoting myself from earlier) Peter (and others), do you have an opinion about whether we should support the fallback/default theme? Given that RTD is the kernel theme, it seems widely available: https://repology.org/project/python:sphinx-rtd-theme/versions. I can update the patch to check if the sphinx_rtd_theme module is present, and error during configure time. thanks
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..5ee577750b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -151,37 +151,44 @@ with open(os.path.join(qemu_docdir, 'defs.rst.inc')) as f: # 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 9d42b5a4b8..957ecdcd50 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 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 0b5053f2d0..db249d1506 100644 --- a/tests/docker/dockerfiles/fedora.docker +++ b/tests/docker/dockerfiles/fedora.docker @@ -89,6 +89,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 ae889d8482..33c19e1762 100644 --- a/tests/docker/dockerfiles/ubuntu2004.docker +++ b/tests/docker/dockerfiles/ubuntu2004.docker @@ -55,6 +55,7 @@ ENV PACKAGES flex bison \ python3-pil \ python3-pip \ python3-sphinx \ + python3-sphinx-rtd-theme \ python3-venv \ python3-yaml \ rpm2cpio \