From: John Snow <jsnow@redhat.com>
To: marcandre.lureau@redhat.com, qemu-devel@nongnu.org
Cc: peter.maydell@linaro.org, bmeng.cn@gmail.com,
berrange@redhat.com, pbonzini@redhat.com
Subject: Re: [PATCH v3] sphinx: adopt kernel readthedoc theme
Date: Thu, 21 Jan 2021 15:58:01 -0500 [thread overview]
Message-ID: <26032f17-cfbc-1e86-1ca1-10661d4f5cbb@redhat.com> (raw)
In-Reply-To: <20210120102556.125012-1-marcandre.lureau@redhat.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 \
>
next prev parent reply other threads:[~2021-01-21 20:59 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-01-20 10:25 [PATCH v3] sphinx: adopt kernel readthedoc theme marcandre.lureau
2021-01-20 10:30 ` no-reply
2021-01-20 12:29 ` Bin Meng
2021-01-21 20:58 ` John Snow [this message]
2021-01-24 18:19 ` Marc-André Lureau
2021-01-25 16:47 ` John Snow
2021-01-25 19:31 ` Marc-André Lureau
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=26032f17-cfbc-1e86-1ca1-10661d4f5cbb@redhat.com \
--to=jsnow@redhat.com \
--cc=berrange@redhat.com \
--cc=bmeng.cn@gmail.com \
--cc=marcandre.lureau@redhat.com \
--cc=pbonzini@redhat.com \
--cc=peter.maydell@linaro.org \
--cc=qemu-devel@nongnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).