From: "Marc-André Lureau" <marcandre.lureau@redhat.com>
To: qemu-devel <qemu-devel@nongnu.org>
Cc: John Snow <jsnow@redhat.com>,
Peter Maydell <peter.maydell@linaro.org>,
bmeng.cn@gmail.com, "P. Berrange, Daniel" <berrange@redhat.com>
Subject: Re: [PATCH v4] sphinx: adopt kernel readthedoc theme
Date: Mon, 22 Mar 2021 15:34:23 +0400 [thread overview]
Message-ID: <CAMxuvazgQ1HGt459VstXB90A3ODD0n1oCFr2oRw7BvspOYdcKw@mail.gmail.com> (raw)
In-Reply-To: <CAMxuvaxZfpSS-5+_hbUjQ78u253FkEi+BiZAVn=YOV7RugzB0w@mail.gmail.com>
[-- Attachment #1: Type: text/plain, Size: 15910 bytes --]
On Mon, Mar 22, 2021 at 2:59 PM Marc-André Lureau <
marcandre.lureau@redhat.com> wrote:
> Hi
>
> On Mon, Mar 22, 2021 at 2:52 PM <marcandre.lureau@redhat.com> wrote:
>
>> From: Marc-André Lureau <marcandre.lureau@redhat.com>
>>
>> The default "alabaster" sphinx theme has a couple shortcomings:
>> - the navbar moves along the page
>> - the search bar is not always at the same place
>> - it lacks some contrast and colours
>>
>> The "rtd" theme from readthedocs.org is a popular third party theme used
>> notably by the kernel, with a custom style sheet. I like it better,
>> perhaps others do too. It also simplify "Edit on Gitlab" links.
>>
>> Tweak a bit the custom theme to match qemu.org style, use the
>> QEMU logo, and favicon etc.
>>
>> Screenshot:
>>
>> https://i.ibb.co/XWwG1bZ/Screenshot-2021-01-20-Welcome-to-QEMU-s-documentation-QEMU-documentation.png
>
>
> Sorry, this link is outdated now. Here is a more stable one:
>
> https://elmarco.fedorapeople.org/Screenshot_2021-03-22%20Welcome%20to%20QEMU%e2%80%99s%20documentation%20%e2%80%94%20QEMU%20documentation.png
>
>
What about simplifying the various section titles?
https://elmarco.fedorapeople.org/Screenshot_2021-03-22%20Welcome%20to%20QEMU%e2%80%99s%20documentation%20%e2%80%94%20QEMU%20documentation(1).png
>>
>> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
>> Tested-by: Bin Meng <bmeng.cn@gmail.com>
>> ---
>> v4:
>> - resend (with Bin T-b, and with minor style fixes)
>>
>> docs/_templates/editpage.html | 5 -
>> docs/conf.py | 50 ++++---
>> docs/devel/_templates/editpage.html | 5 -
>> docs/interop/_templates/editpage.html | 5 -
>> docs/specs/_templates/editpage.html | 5 -
>> docs/sphinx-static/theme_overrides.css | 161 +++++++++++++++++++++
>> docs/system/_templates/editpage.html | 5 -
>> docs/tools/_templates/editpage.html | 5 -
>> docs/user/_templates/editpage.html | 5 -
>> tests/docker/dockerfiles/debian10.docker | 1 +
>> tests/docker/dockerfiles/fedora.docker | 1 +
>> tests/docker/dockerfiles/ubuntu.docker | 1 +
>> tests/docker/dockerfiles/ubuntu1804.docker | 1 +
>> tests/docker/dockerfiles/ubuntu2004.docker | 1 +
>> 14 files changed, 196 insertions(+), 55 deletions(-)
>> delete mode 100644 docs/_templates/editpage.html
>> delete mode 100644 docs/devel/_templates/editpage.html
>> delete mode 100644 docs/interop/_templates/editpage.html
>> delete mode 100644 docs/specs/_templates/editpage.html
>> create mode 100644 docs/sphinx-static/theme_overrides.css
>> delete mode 100644 docs/system/_templates/editpage.html
>> delete mode 100644 docs/tools/_templates/editpage.html
>> delete mode 100644 docs/user/_templates/editpage.html
>>
>> diff --git a/docs/_templates/editpage.html b/docs/_templates/editpage.html
>> deleted file mode 100644
>> index 4319b0f5ac..0000000000
>> --- a/docs/_templates/editpage.html
>> +++ /dev/null
>> @@ -1,5 +0,0 @@
>> -<div id="editpage">
>> - <ul>
>> - <li><a href="
>> https://gitlab.com/qemu-project/qemu/-/blob/master/docs/{{pagename}}.rst">Page
>> source</a></li>
>> - </ul>
>> -</div>
>> diff --git a/docs/conf.py b/docs/conf.py
>> index 2ee6111872..17e0319d69 100644
>> --- a/docs/conf.py
>> +++ b/docs/conf.py
>> @@ -151,37 +151,47 @@
>> # a list of builtin themes.
>> #
>> html_theme = 'alabaster'
>> +try:
>> + import sphinx_rtd_theme
>> + html_theme = 'sphinx_rtd_theme'
>> +except ImportError:
>> + sys.stderr.write(
>> + 'Warning: The Sphinx \'sphinx_rtd_theme\' HTML theme was not
>> found. '
>> + 'Make sure you have the theme installed to produce pretty HTML '
>> + 'output. Falling back to the default theme.\n')
>>
>> # Theme options are theme-specific and customize the look and feel of a
>> theme
>> # further. For a list of options available for each theme, see the
>> # documentation.
>> -# We initialize this to empty here, so the per-manual conf.py can just
>> -# add individual key/value entries.
>> -html_theme_options = {
>> -}
>> +if html_theme == 'sphinx_rtd_theme':
>> + html_theme_options = {
>> + "style_nav_header_background": "#802400",
>> + }
>> +
>> +html_logo = os.path.join(qemu_docdir, "../ui/icons/qemu_128x128.png")
>> +
>> +html_favicon = os.path.join(qemu_docdir, "../ui/icons/qemu_32x32.png")
>>
>> # Add any paths that contain custom static files (such as style sheets)
>> here,
>> # relative to this directory. They are copied after the builtin static
>> files,
>> # so a file named "default.css" will overwrite the builtin "default.css".
>> -# QEMU doesn't yet have any static files, so comment this out so we don't
>> -# get a warning about a missing directory.
>> -# If we do ever add this then it would probably be better to call the
>> -# subdirectory sphinx_static, as the Linux kernel does.
>> -# html_static_path = ['_static']
>> +html_static_path = [os.path.join(qemu_docdir, "sphinx-static")]
>> +
>> +html_css_files = [
>> + 'theme_overrides.css',
>> +]
>> +
>> +html_context = {
>> + "display_gitlab": True,
>> + "gitlab_user": "qemu-project",
>> + "gitlab_repo": "qemu",
>> + "gitlab_version": "master",
>> + "conf_py_path": "/docs/", # Path in the checkout to the docs root
>> +}
>>
>> # Custom sidebar templates, must be a dictionary that maps document names
>> # to template names.
>> -#
>> -# This is required for the alabaster theme
>> -# refs:
>> http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
>> -html_sidebars
>> <http://alabaster.readthedocs.io/en/latest/installation.html#sidebars-html_sidebars>
>> = {
>> - '**': [
>> - 'about.html',
>> - 'editpage.html',
>> - 'navigation.html',
>> - 'searchbox.html',
>> - ]
>> -}
>> +#html_sidebars = {}
>>
>> # Don't copy the rST source files to the HTML output directory,
>> # and don't put links to the sources into the output HTML.
>> diff --git a/docs/devel/_templates/editpage.html
>> b/docs/devel/_templates/editpage.html
>> deleted file mode 100644
>> index a86d22bca8..0000000000
>> --- a/docs/devel/_templates/editpage.html
>> +++ /dev/null
>> @@ -1,5 +0,0 @@
>> -<div id="editpage">
>> - <ul>
>> - <li><a href="
>> https://gitlab.com/qemu-project/qemu/-/blob/master/docs/devel/{{pagename}}.rst">Page
>> source</a></li>
>> - </ul>
>> -</div>
>> diff --git a/docs/interop/_templates/editpage.html
>> b/docs/interop/_templates/editpage.html
>> deleted file mode 100644
>> index 215e562681..0000000000
>> --- a/docs/interop/_templates/editpage.html
>> +++ /dev/null
>> @@ -1,5 +0,0 @@
>> -<div id="editpage">
>> - <ul>
>> - <li><a href="
>> https://gitlab.com/qemu-project/qemu/-/blob/master/docs/interop/{{pagename}}.rst">Page
>> source</a></li>
>> - </ul>
>> -</div>
>> diff --git a/docs/specs/_templates/editpage.html
>> b/docs/specs/_templates/editpage.html
>> deleted file mode 100644
>> index aaa468aa98..0000000000
>> --- a/docs/specs/_templates/editpage.html
>> +++ /dev/null
>> @@ -1,5 +0,0 @@
>> -<div id="editpage">
>> - <ul>
>> - <li><a href="
>> https://gitlab.com/qemu-project/qemu/-/blob/master/docs/specs/{{pagename}}.rst">Page
>> source</a></li>
>> - </ul>
>> -</div>
>> diff --git a/docs/sphinx-static/theme_overrides.css
>> b/docs/sphinx-static/theme_overrides.css
>> new file mode 100644
>> index 0000000000..c70ef95128
>> --- /dev/null
>> +++ b/docs/sphinx-static/theme_overrides.css
>> @@ -0,0 +1,161 @@
>> +/* -*- coding: utf-8; mode: css -*-
>> + *
>> + * Sphinx HTML theme customization: read the doc
>> + * Based on Linux Documentation/sphinx-static/theme_overrides.css
>> + */
>> +
>> +/* Improve contrast and increase size for easier reading. */
>> +
>> +body {
>> + font-family: serif;
>> + color: black;
>> + font-size: 100%;
>> +}
>> +
>> +h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend {
>> + font-family: sans-serif;
>> +}
>> +
>> +.rst-content dl:not(.docutils) dt {
>> + border-top: none;
>> + border-left: solid 3px #ccc;
>> + background-color: #f0f0f0;
>> + color: black;
>> +}
>> +
>> +.wy-nav-top {
>> + background: #802400;
>> +}
>> +
>> +.wy-side-nav-search input[type="text"] {
>> + border-color: #f60;
>> +}
>> +
>> +.wy-menu-vertical p.caption {
>> + color: white;
>> +}
>> +
>> +.wy-menu-vertical li.current a {
>> + color: #505050;
>> +}
>> +
>> +.wy-menu-vertical li.on a, .wy-menu-vertical li.current > a {
>> + color: #303030;
>> +}
>> +
>> +.fa-gitlab {
>> + box-shadow: 0 4px 8px 0 rgba(0,0,0,0.2), 0 3px 10px 0
>> rgba(0,0,0,0.19);
>> + border-radius: 5px;
>> +}
>> +
>> +div[class^="highlight"] pre {
>> + font-family: monospace;
>> + color: black;
>> + font-size: 100%;
>> +}
>> +
>> +.wy-menu-vertical {
>> + font-family: sans-serif;
>> +}
>> +
>> +.c {
>> + font-style: normal;
>> +}
>> +
>> +p {
>> + font-size: 100%;
>> +}
>> +
>> +/* Interim: Code-blocks with line nos - lines and line numbers don't
>> line up.
>> + * see: https://github.com/rtfd/sphinx_rtd_theme/issues/419
>> + */
>> +
>> +div[class^="highlight"] pre {
>> + line-height: normal;
>> +}
>> +.rst-content .highlight > pre {
>> + line-height: normal;
>> +}
>> +
>> +/* Keep fields from being strangely far apart due to inheirited table
>> CSS. */
>> +.rst-content table.field-list th.field-name {
>> + padding-top: 1px;
>> + padding-bottom: 1px;
>> +}
>> +.rst-content table.field-list td.field-body {
>> + padding-top: 1px;
>> + padding-bottom: 1px;
>> +}
>> +
>> +@media screen {
>> +
>> + /* content column
>> + *
>> + * RTD theme's default is 800px as max width for the content, but we
>> have
>> + * tables with tons of columns, which need the full width of the
>> view-port.
>> + */
>> +
>> + .wy-nav-content{max-width: none; }
>> +
>> + /* table:
>> + *
>> + * - Sequences of whitespace should collapse into a single
>> whitespace.
>> + * - make the overflow auto (scrollbar if needed)
>> + * - align caption "left" ("center" is unsuitable on vast tables)
>> + */
>> +
>> + .wy-table-responsive table td { white-space: normal; }
>> + .wy-table-responsive { overflow: auto; }
>> + .rst-content table.docutils caption { text-align: left; font-size:
>> 100%; }
>> +
>> + /* captions:
>> + *
>> + * - captions should have 100% (not 85%) font size
>> + * - hide the permalink symbol as long as link is not hovered
>> + */
>> +
>> + .toc-title {
>> + font-size: 150%;
>> + font-weight: bold;
>> + }
>> +
>> + caption, .wy-table caption, .rst-content table.field-list caption {
>> + font-size: 100%;
>> + }
>> + caption a.headerlink { opacity: 0; }
>> + caption a.headerlink:hover { opacity: 1; }
>> +
>> + /* Menu selection and keystrokes */
>> +
>> + span.menuselection {
>> + color: blue;
>> + font-family: "Courier New", Courier, monospace
>> + }
>> +
>> + code.kbd, code.kbd span {
>> + color: white;
>> + background-color: darkblue;
>> + font-weight: bold;
>> + font-family: "Courier New", Courier, monospace
>> + }
>> +
>> + /* fix bottom margin of lists items */
>> +
>> + .rst-content .section ul li:last-child, .rst-content .section ul li
>> p:last-child {
>> + margin-bottom: 12px;
>> + }
>> +
>> + /* inline literal: drop the borderbox, padding and red color */
>> +
>> + code, .rst-content tt, .rst-content code {
>> + color: inherit;
>> + border: none;
>> + padding: unset;
>> + background: inherit;
>> + font-size: 85%;
>> + }
>> +
>> + .rst-content tt.literal,.rst-content tt.literal,.rst-content
>> code.literal {
>> + color: inherit;
>> + }
>> +}
>> diff --git a/docs/system/_templates/editpage.html
>> b/docs/system/_templates/editpage.html
>> deleted file mode 100644
>> index 6586b2e257..0000000000
>> --- a/docs/system/_templates/editpage.html
>> +++ /dev/null
>> @@ -1,5 +0,0 @@
>> -<div id="editpage">
>> - <ul>
>> - <li><a href="
>> https://gitlab.com/qemu-project/qemu/-/blob/master/docs/system/{{pagename}}.rst">Page
>> source</a></li>
>> - </ul>
>> -</div>
>> diff --git a/docs/tools/_templates/editpage.html
>> b/docs/tools/_templates/editpage.html
>> deleted file mode 100644
>> index 2a9c8fc92b..0000000000
>> --- a/docs/tools/_templates/editpage.html
>> +++ /dev/null
>> @@ -1,5 +0,0 @@
>> -<div id="editpage">
>> - <ul>
>> - <li><a href="
>> https://gitlab.com/qemu-project/qemu/-/blob/master/docs/tools/{{pagename}}.rst">Page
>> source</a></li>
>> - </ul>
>> -</div>
>> diff --git a/docs/user/_templates/editpage.html
>> b/docs/user/_templates/editpage.html
>> deleted file mode 100644
>> index 1f5ee01e60..0000000000
>> --- a/docs/user/_templates/editpage.html
>> +++ /dev/null
>> @@ -1,5 +0,0 @@
>> -<div id="editpage">
>> - <ul>
>> - <li><a href="
>> https://gitlab.com/qemu-project/qemu/-/blob/master/docs/user/{{pagename}}.rst">Page
>> source</a></li>
>> - </ul>
>> -</div>
>> diff --git a/tests/docker/dockerfiles/debian10.docker
>> b/tests/docker/dockerfiles/debian10.docker
>> index d034acbd25..63cf835ec5 100644
>> --- a/tests/docker/dockerfiles/debian10.docker
>> +++ b/tests/docker/dockerfiles/debian10.docker
>> @@ -32,6 +32,7 @@ RUN apt update && \
>> psmisc \
>> python3 \
>> python3-sphinx \
>> + python3-sphinx-rtd-theme \
>> $(apt-get -s build-dep --arch-only qemu | egrep ^Inst | fgrep
>> '[all]' | cut -d\ -f2)
>>
>> ENV FEATURES docs
>> diff --git a/tests/docker/dockerfiles/fedora.docker
>> b/tests/docker/dockerfiles/fedora.docker
>> index 915fdc1845..d8fa16372d 100644
>> --- a/tests/docker/dockerfiles/fedora.docker
>> +++ b/tests/docker/dockerfiles/fedora.docker
>> @@ -92,6 +92,7 @@ ENV PACKAGES \
>> python3-pillow \
>> python3-pip \
>> python3-sphinx \
>> + python3-sphinx_rtd_theme \
>> python3-virtualenv \
>> rdma-core-devel \
>> SDL2-devel \
>> diff --git a/tests/docker/dockerfiles/ubuntu.docker
>> b/tests/docker/dockerfiles/ubuntu.docker
>> index b5ef7a8198..98a527361c 100644
>> --- a/tests/docker/dockerfiles/ubuntu.docker
>> +++ b/tests/docker/dockerfiles/ubuntu.docker
>> @@ -63,6 +63,7 @@ ENV PACKAGES \
>> ninja-build \
>> python3-yaml \
>> python3-sphinx \
>> + python3-sphinx-rtd-theme \
>> sparse \
>> xfslibs-dev
>> RUN apt-get update && \
>> diff --git a/tests/docker/dockerfiles/ubuntu1804.docker
>> b/tests/docker/dockerfiles/ubuntu1804.docker
>> index 9b0a19ba5e..c0d3642507 100644
>> --- a/tests/docker/dockerfiles/ubuntu1804.docker
>> +++ b/tests/docker/dockerfiles/ubuntu1804.docker
>> @@ -48,6 +48,7 @@ ENV PACKAGES \
>> make \
>> python3-yaml \
>> python3-sphinx \
>> + python3-sphinx-rtd-theme \
>> ninja-build \
>> sparse \
>> xfslibs-dev
>> diff --git a/tests/docker/dockerfiles/ubuntu2004.docker
>> b/tests/docker/dockerfiles/ubuntu2004.docker
>> index 9750016e51..f1e0ebad49 100644
>> --- a/tests/docker/dockerfiles/ubuntu2004.docker
>> +++ b/tests/docker/dockerfiles/ubuntu2004.docker
>> @@ -58,6 +58,7 @@ ENV PACKAGES flex bison \
>> python3-pil \
>> python3-pip \
>> python3-sphinx \
>> + python3-sphinx-rtd-theme \
>> python3-venv \
>> python3-yaml \
>> rpm2cpio \
>> --
>> 2.29.0
>>
>>
[-- Attachment #2: Type: text/html, Size: 20520 bytes --]
next prev parent reply other threads:[~2021-03-22 11:36 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-03-22 10:52 [PATCH v4] sphinx: adopt kernel readthedoc theme marcandre.lureau
2021-03-22 10:59 ` Marc-André Lureau
2021-03-22 11:34 ` Marc-André Lureau [this message]
2021-03-22 12:14 ` Daniel P. Berrangé
2021-03-23 10:27 ` Daniel P. Berrangé
2021-03-23 11:00 ` Peter Maydell
2021-03-23 11:12 ` Marc-André Lureau
2021-03-23 11:29 ` Daniel P. Berrangé
2021-03-23 11:36 ` Peter Maydell
2021-03-23 11:37 ` Marc-André Lureau
2021-03-23 11:05 ` 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=CAMxuvazgQ1HGt459VstXB90A3ODD0n1oCFr2oRw7BvspOYdcKw@mail.gmail.com \
--to=marcandre.lureau@redhat.com \
--cc=berrange@redhat.com \
--cc=bmeng.cn@gmail.com \
--cc=jsnow@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).