From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-15.6 required=3.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,HEADER_FROM_DIFFERENT_DOMAINS,HTML_MESSAGE,INCLUDES_CR_TRAILER, INCLUDES_PATCH,MAILING_LIST_MULTI,MENTIONS_GIT_HOSTING,SPF_HELO_NONE,SPF_PASS, URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 1396DC433C1 for ; Mon, 22 Mar 2021 11:05:40 +0000 (UTC) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 8457561931 for ; Mon, 22 Mar 2021 11:05:39 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 8457561931 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:48176 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lOINO-0004it-I2 for qemu-devel@archiver.kernel.org; Mon, 22 Mar 2021 07:05:38 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:42482) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lOIHj-0000F9-Gk for qemu-devel@nongnu.org; Mon, 22 Mar 2021 06:59:47 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:54646) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lOIHe-0007T2-I1 for qemu-devel@nongnu.org; Mon, 22 Mar 2021 06:59:47 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1616410781; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=ISGXTUea0+j8A7+kcMw6Wxg4DUsMX0+y5YDZ8DW2I7U=; b=BkZeOxoXQG5dJBRrS0RrDUXIFo73Q3fA75zGfGRq0xYCeq3komPC0zZSFURH8wz4K6B+ab i9V9njYhDYelkRJRFOb/Swknz8OC7OGPjOc5Xk/NcVyMvX6lqnxMjUYpFgkEu0k8U34MvT AKCEWuzzwt/vxJqTe0VfO1MqmT+GUy8= Received: from mail-io1-f69.google.com (mail-io1-f69.google.com [209.85.166.69]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-251-xBbYLLC5PuSekKDA8fdaRA-1; Mon, 22 Mar 2021 06:59:37 -0400 X-MC-Unique: xBbYLLC5PuSekKDA8fdaRA-1 Received: by mail-io1-f69.google.com with SMTP id d4so33574814ioc.16 for ; Mon, 22 Mar 2021 03:59:37 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=ISGXTUea0+j8A7+kcMw6Wxg4DUsMX0+y5YDZ8DW2I7U=; b=OaZPGO+Fg1j9u/ZibNsjokcvdi44nTNXrL4Bn01l9CkQtzmz2rV+UDn9QnQnvHVzhI BKafU5UAn2W1GPyDL6h5xsHzyjdYDSvVLlOXB3b4c9RJnheCLa8wgJbfS79ETEDOUTkc hcB115yqg+q7T3xcYbNrZuJhKFmVe82IqGfinkjWrXhZrO8MdAow4iPKBDJkWB8r+BYM 52Zw+P6zxXORGNSKp8988eR4oXUMgblk36e6SVuxrfIKPdXV/DjIvax4jLilY2zFS4RL TnMFOHd56QoqDz2HH0+EW67naOhxVApqJnSiS2hjTZDCQ0YarlXoNro3mj8cy1zS/48o L4Rg== X-Gm-Message-State: AOAM530fyXZpModjgx+MM91n2WDGoMyU4nFB4iZzF8Ivma6eloIP5Kp3 8vPH43qNPr8KpcdxJRoLGkmq2kZkVbDpu8EEIdPbwOVoKD4ZJvSKPeES9VB7zuuzjdbxu6QXi+A u6iXBSkPZaGSV7IjisEwq5ki75ZdAC/8= X-Received: by 2002:a05:6602:2e82:: with SMTP id m2mr10120668iow.70.1616410776611; Mon, 22 Mar 2021 03:59:36 -0700 (PDT) X-Google-Smtp-Source: ABdhPJxreMO1mtPH1bf4A6sDZ5mpFeqhR/r3zkOg7TOYNktDj925rwQ0mVMJTymGfYnql1SmzxO7T9ssvyPIoXpzO+0= X-Received: by 2002:a05:6602:2e82:: with SMTP id m2mr10120657iow.70.1616410776372; Mon, 22 Mar 2021 03:59:36 -0700 (PDT) MIME-Version: 1.0 References: <20210322105234.3932691-1-marcandre.lureau@redhat.com> In-Reply-To: <20210322105234.3932691-1-marcandre.lureau@redhat.com> From: =?UTF-8?B?TWFyYy1BbmRyw6kgTHVyZWF1?= Date: Mon, 22 Mar 2021 14:59:25 +0400 Message-ID: Subject: Re: [PATCH v4] sphinx: adopt kernel readthedoc theme To: qemu-devel Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=mlureau@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: multipart/alternative; boundary="00000000000023193005be1df630" Received-SPF: pass client-ip=216.205.24.124; envelope-from=mlureau@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, HTML_MESSAGE=0.001, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H4=-0.01, RCVD_IN_MSPIKE_WL=-0.01, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: John Snow , Peter Maydell , bmeng.cn@gmail.com, "P. Berrange, Daniel" Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" --00000000000023193005be1df630 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Hi On Mon, Mar 22, 2021 at 2:52 PM wrote: > From: Marc-Andr=C3=A9 Lureau > > 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-document= ation-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%20QEM= U%e2%80%99s%20documentation%20%e2%80%94%20QEMU%20documentation.png > > Signed-off-by: Marc-Andr=C3=A9 Lureau > Tested-by: Bin Meng > --- > 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.htm= l > deleted file mode 100644 > index 4319b0f5ac..0000000000 > --- a/docs/_templates/editpage.html > +++ /dev/null > @@ -1,5 +0,0 @@ > - > 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 =3D 'alabaster' > +try: > + import sphinx_rtd_theme > + html_theme =3D '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 =3D { > -} > +if html_theme =3D=3D 'sphinx_rtd_theme': > + html_theme_options =3D { > + "style_nav_header_background": "#802400", > + } > + > +html_logo =3D os.path.join(qemu_docdir, "../ui/icons/qemu_128x128.png") > + > +html_favicon =3D 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 =3D ['_static'] > +html_static_path =3D [os.path.join(qemu_docdir, "sphinx-static")] > + > +html_css_files =3D [ > + 'theme_overrides.css', > +] > + > +html_context =3D { > + "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 name= s > # to template names. > -# > -# This is required for the alabaster theme > -# refs: > http://alabaster.readthedocs.io/en/latest/installation.html#sidebars > -html_sidebars > > =3D { > - '**': [ > - 'about.html', > - 'editpage.html', > - 'navigation.html', > - 'searchbox.html', > - ] > -} > +#html_sidebars =3D {} > > # 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 @@ > - > 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 @@ > - > 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 @@ > - > 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=3D"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^=3D"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 lin= e > up. > + * see: https://github.com/rtfd/sphinx_rtd_theme/issues/419 > + */ > + > +div[class^=3D"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 @@ > - > 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 @@ > - > 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 @@ > - > 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 > > --00000000000023193005be1df630 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
Hi

On Mon, Mar 22, 2021 at 2:52 PM <marcandre.lureau@redhat.com>= wrote:
From: Ma= rc-Andr=C3=A9 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 th= eme 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-documenta= tion-QEMU-documentation.png

Sorry, this= link is outdated now. Here is a more stable one:
<= br>


Signed-off-by: Marc-Andr=C3=A9 Lureau <marcandre.lureau@redhat.com>
Tested-by: Bin Meng <bmeng.cn@gmail.com>
---
v4:
=C2=A0- resend (with Bin T-b, and with minor style fixes)

=C2=A0docs/_templates/editpage.html=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2= =A0 =C2=A0 |=C2=A0 =C2=A05 -
=C2=A0docs/conf.py=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0|=C2=A0 50 ++++--- =C2=A0docs/devel/_templates/editpage.html=C2=A0 =C2=A0 =C2=A0 =C2=A0 |=C2= =A0 =C2=A05 -
=C2=A0docs/interop/_templates/editpage.html=C2=A0 =C2=A0 =C2=A0 |=C2=A0 =C2= =A05 -
=C2=A0docs/specs/_templates/editpage.html=C2=A0 =C2=A0 =C2=A0 =C2=A0 |=C2= =A0 =C2=A05 -
=C2=A0docs/sphinx-static/theme_overrides.css=C2=A0 =C2=A0 =C2=A0| 161 +++++= ++++++++++++++++
=C2=A0docs/system/_templates/editpage.html=C2=A0 =C2=A0 =C2=A0 =C2=A0|=C2= =A0 =C2=A05 -
=C2=A0docs/tools/_templates/editpage.html=C2=A0 =C2=A0 =C2=A0 =C2=A0 |=C2= =A0 =C2=A05 -
=C2=A0docs/user/_templates/editpage.html=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0|= =C2=A0 =C2=A05 -
=C2=A0tests/docker/dockerfiles/debian10.docker=C2=A0 =C2=A0|=C2=A0 =C2=A01 = +
=C2=A0tests/docker/dockerfiles/fedora.docker=C2=A0 =C2=A0 =C2=A0|=C2=A0 =C2= =A01 +
=C2=A0tests/docker/dockerfiles/ubuntu.docker=C2=A0 =C2=A0 =C2=A0|=C2=A0 =C2= =A01 +
=C2=A0tests/docker/dockerfiles/ubuntu1804.docker |=C2=A0 =C2=A01 +
=C2=A0tests/docker/dockerfiles/ubuntu2004.docker |=C2=A0 =C2=A01 +
=C2=A014 files changed, 196 insertions(+), 55 deletions(-)
=C2=A0delete mode 100644 docs/_templates/editpage.html
=C2=A0delete mode 100644 docs/devel/_templates/editpage.html
=C2=A0delete mode 100644 docs/interop/_templates/editpage.html
=C2=A0delete mode 100644 docs/specs/_templates/editpage.html
=C2=A0create mode 100644 docs/sphinx-static/theme_overrides.css
=C2=A0delete mode 100644 docs/system/_templates/editpage.html
=C2=A0delete mode 100644 docs/tools/_templates/editpage.html
=C2=A0delete mode 100644 docs/user/_templates/editpage.html

diff --git a/docs/_templates/editpage.html b/docs/_templates/editpage.html<= br> deleted file mode 100644
index 4319b0f5ac..0000000000
--- a/docs/_templates/editpage.html
+++ /dev/null
@@ -1,5 +0,0 @@
-<div id=3D"editpage">
-=C2=A0 <ul>
-=C2=A0 =C2=A0 <li><a href=3D"https://gitlab.com/qemu-project/qemu/-/blob/master/= docs/{{pagename}}.rst">Page source</a></li>
-=C2=A0 </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 @@
=C2=A0# a list of builtin themes.
=C2=A0#
=C2=A0html_theme =3D 'alabaster'
+try:
+=C2=A0 =C2=A0 import sphinx_rtd_theme
+=C2=A0 =C2=A0 html_theme =3D 'sphinx_rtd_theme'
+except ImportError:
+=C2=A0 =C2=A0 sys.stderr.write(
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 'Warning: The Sphinx \'sphinx_rtd_them= e\' HTML theme was not found. '
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 'Make sure you have the theme installed to= produce pretty HTML '
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 'output. Falling back to the default theme= .\n')

=C2=A0# Theme options are theme-specific and customize the look and feel of= a theme
=C2=A0# further.=C2=A0 For a list of options available for each theme, see = the
=C2=A0# documentation.
-# We initialize this to empty here, so the per-manual conf.py can just
-# add individual key/value entries.
-html_theme_options =3D {
-}
+if html_theme =3D=3D 'sphinx_rtd_theme':
+=C2=A0 =C2=A0 html_theme_options =3D {
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 "style_nav_header_background": "= ;#802400",
+=C2=A0 =C2=A0 }
+
+html_logo =3D os.path.join(qemu_docdir, "../ui/icons/qemu_128x128.png= ")
+
+html_favicon =3D os.path.join(qemu_docdir, "../ui/icons/qemu_32x32.pn= g")

=C2=A0# Add any paths that contain custom static files (such as style sheet= s) here,
=C2=A0# relative to this directory. They are copied after the builtin stati= c files,
=C2=A0# 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 do= n'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 =3D ['_static']
+html_static_path =3D [os.path.join(qemu_docdir, "sphinx-static")= ]
+
+html_css_files =3D [
+=C2=A0 =C2=A0 'theme_overrides.css',
+]
+
+html_context =3D {
+=C2=A0 =C2=A0 "display_gitlab": True,
+=C2=A0 =C2=A0 "gitlab_user": "qemu-project",
+=C2=A0 =C2=A0 "gitlab_repo": "qemu",
+=C2=A0 =C2=A0 "gitlab_version": "master",
+=C2=A0 =C2=A0 "conf_py_path": "/docs/", # Path in the = checkout to the docs root
+}

=C2=A0# Custom sidebar templates, must be a dictionary that maps document n= ames
=C2=A0# to template names.
-#
-# This is required for the alabaster theme
-# refs: http://al= abaster.readthedocs.io/en/latest/installation.html#sidebars
-html_sidebars =3D {
-=C2=A0 =C2=A0 '**': [
-=C2=A0 =C2=A0 =C2=A0 =C2=A0 'about.html',
-=C2=A0 =C2=A0 =C2=A0 =C2=A0 'editpage.html',
-=C2=A0 =C2=A0 =C2=A0 =C2=A0 'navigation.html',
-=C2=A0 =C2=A0 =C2=A0 =C2=A0 'searchbox.html',
-=C2=A0 =C2=A0 ]
-}
+#html_sidebars =3D {}

=C2=A0# Don't copy the rST source files to the HTML output directory, =C2=A0# and don't put links to the sources into the output HTML.
diff --git a/docs/devel/_templates/editpage.html b/docs/devel/_templates/ed= itpage.html
deleted file mode 100644
index a86d22bca8..0000000000
--- a/docs/devel/_templates/editpage.html
+++ /dev/null
@@ -1,5 +0,0 @@
-<div id=3D"editpage">
-=C2=A0 <ul>
-=C2=A0 =C2=A0 <li><a href=3D"https://gitlab.com/qemu-project/qemu/-/blob/m= aster/docs/devel/{{pagename}}.rst">Page source</a></li= >
-=C2=A0 </ul>
-</div>
diff --git a/docs/interop/_templates/editpage.html b/docs/interop/_template= s/editpage.html
deleted file mode 100644
index 215e562681..0000000000
--- a/docs/interop/_templates/editpage.html
+++ /dev/null
@@ -1,5 +0,0 @@
-<div id=3D"editpage">
-=C2=A0 <ul>
-=C2=A0 =C2=A0 <li><a href=3D"https://gitlab.com/qemu-project/qemu/-/bl= ob/master/docs/interop/{{pagename}}.rst">Page source</a>&= lt;/li>
-=C2=A0 </ul>
-</div>
diff --git a/docs/specs/_templates/editpage.html b/docs/specs/_templates/ed= itpage.html
deleted file mode 100644
index aaa468aa98..0000000000
--- a/docs/specs/_templates/editpage.html
+++ /dev/null
@@ -1,5 +0,0 @@
-<div id=3D"editpage">
-=C2=A0 <ul>
-=C2=A0 =C2=A0 <li><a href=3D"https://gitlab.com/qemu-project/qemu/-/blob/m= aster/docs/specs/{{pagename}}.rst">Page source</a></li= >
-=C2=A0 </ul>
-</div>
diff --git a/docs/sphinx-static/theme_overrides.css b/docs/sphinx-static/th= eme_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 {
+=C2=A0 =C2=A0 font-family: serif;
+=C2=A0 =C2=A0 color: black;
+=C2=A0 =C2=A0 font-size: 100%;
+}
+
+h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend {<= br> +=C2=A0 =C2=A0 font-family: sans-serif;
+}
+
+.rst-content dl:not(.docutils) dt {
+=C2=A0 =C2=A0 border-top: none;
+=C2=A0 =C2=A0 border-left: solid 3px #ccc;
+=C2=A0 =C2=A0 background-color: #f0f0f0;
+=C2=A0 =C2=A0 color: black;
+}
+
+.wy-nav-top {
+=C2=A0 =C2=A0 background: #802400;
+}
+
+.wy-side-nav-search input[type=3D"text"] {
+=C2=A0 =C2=A0 border-color: #f60;
+}
+
+.wy-menu-vertical p.caption {
+=C2=A0 =C2=A0 color: white;
+}
+
+.wy-menu-vertical li.current a {
+=C2=A0 =C2=A0 color: #505050;
+}
+
+.wy-menu-vertical li.on a, .wy-menu-vertical li.current > a {
+=C2=A0 =C2=A0 color: #303030;
+}
+
+.fa-gitlab {
+=C2=A0 =C2=A0 =C2=A0 box-shadow: 0 4px 8px 0 rgba(0,0,0,0.2), 0 3px 10px 0= rgba(0,0,0,0.19);
+=C2=A0 =C2=A0 =C2=A0 border-radius: 5px;
+}
+
+div[class^=3D"highlight"] pre {
+=C2=A0 =C2=A0 font-family: monospace;
+=C2=A0 =C2=A0 color: black;
+=C2=A0 =C2=A0 font-size: 100%;
+}
+
+.wy-menu-vertical {
+=C2=A0 =C2=A0 font-family: sans-serif;
+}
+
+.c {
+=C2=A0 =C2=A0 font-style: normal;
+}
+
+p {
+=C2=A0 =C2=A0 font-size: 100%;
+}
+
+/* Interim: Code-blocks with line nos - lines and line numbers don't l= ine up.
+ * see: https://github.com/rtfd/sphinx_rtd_theme= /issues/419
+ */
+
+div[class^=3D"highlight"] pre {
+=C2=A0 =C2=A0 line-height: normal;
+}
+.rst-content .highlight > pre {
+=C2=A0 =C2=A0 line-height: normal;
+}
+
+/* Keep fields from being strangely far apart due to inheirited table CSS.= */
+.rst-content table.field-list th.field-name {
+=C2=A0 =C2=A0 padding-top: 1px;
+=C2=A0 =C2=A0 padding-bottom: 1px;
+}
+.rst-content table.field-list td.field-body {
+=C2=A0 =C2=A0 padding-top: 1px;
+=C2=A0 =C2=A0 padding-bottom: 1px;
+}
+
+@media screen {
+
+=C2=A0 =C2=A0 /* content column
+=C2=A0 =C2=A0 =C2=A0*
+=C2=A0 =C2=A0 =C2=A0* RTD theme's default is 800px as max width for th= e content, but we have
+=C2=A0 =C2=A0 =C2=A0* tables with tons of columns, which need the full wid= th of the view-port.
+=C2=A0 =C2=A0 =C2=A0*/
+
+=C2=A0 =C2=A0 .wy-nav-content{max-width: none; }
+
+=C2=A0 =C2=A0 /* table:
+=C2=A0 =C2=A0 =C2=A0*
+=C2=A0 =C2=A0 =C2=A0*=C2=A0 =C2=A0- Sequences of whitespace should collaps= e into a single whitespace.
+=C2=A0 =C2=A0 =C2=A0*=C2=A0 =C2=A0- make the overflow auto (scrollbar if n= eeded)
+=C2=A0 =C2=A0 =C2=A0*=C2=A0 =C2=A0- align caption "left" ("= center" is unsuitable on vast tables)
+=C2=A0 =C2=A0 =C2=A0*/
+
+=C2=A0 =C2=A0 .wy-table-responsive table td { white-space: normal; }
+=C2=A0 =C2=A0 .wy-table-responsive { overflow: auto; }
+=C2=A0 =C2=A0 .rst-content table.docutils caption { text-align: left; font= -size: 100%; }
+
+=C2=A0 =C2=A0 /* captions:
+=C2=A0 =C2=A0 =C2=A0*
+=C2=A0 =C2=A0 =C2=A0*=C2=A0 =C2=A0- captions should have 100% (not 85%) fo= nt size
+=C2=A0 =C2=A0 =C2=A0*=C2=A0 =C2=A0- hide the permalink symbol as long as l= ink is not hovered
+=C2=A0 =C2=A0 =C2=A0*/
+
+=C2=A0 =C2=A0 .toc-title {
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 font-size: 150%;
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 font-weight: bold;
+=C2=A0 =C2=A0 }
+
+=C2=A0 =C2=A0 caption, .wy-table caption, .rst-content table.field-list ca= ption {
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 font-size: 100%;
+=C2=A0 =C2=A0 }
+=C2=A0 =C2=A0 caption a.headerlink { opacity: 0; }
+=C2=A0 =C2=A0 caption a.headerlink:hover { opacity: 1; }
+
+=C2=A0 =C2=A0 /* Menu selection and keystrokes */
+
+=C2=A0 =C2=A0 span.menuselection {
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 color: blue;
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 font-family: "Courier New", Courier,= monospace
+=C2=A0 =C2=A0 }
+
+=C2=A0 =C2=A0 code.kbd, code.kbd span {
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 color: white;
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 background-color: darkblue;
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 font-weight: bold;
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 font-family: "Courier New", Courier,= monospace
+=C2=A0 =C2=A0 }
+
+=C2=A0 =C2=A0 /* fix bottom margin of lists items */
+
+=C2=A0 =C2=A0 .rst-content .section ul li:last-child, .rst-content .sectio= n ul li p:last-child {
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 margin-bottom: 12px;
+=C2=A0 =C2=A0 }
+
+=C2=A0 =C2=A0 /* inline literal: drop the borderbox, padding and red color= */
+
+=C2=A0 =C2=A0 code, .rst-content tt, .rst-content code {
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 color: inherit;
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 border: none;
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 padding: unset;
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 background: inherit;
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 font-size: 85%;
+=C2=A0 =C2=A0 }
+
+=C2=A0 =C2=A0 .rst-content tt.literal,.rst-content tt.literal,.rst-content= code.literal {
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 color: inherit;
+=C2=A0 =C2=A0 }
+}
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=3D"editpage">
-=C2=A0 <ul>
-=C2=A0 =C2=A0 <li><a href=3D"https://gitlab.com/qemu-project/qemu/-/blob/= master/docs/system/{{pagename}}.rst">Page source</a></= li>
-=C2=A0 </ul>
-</div>
diff --git a/docs/tools/_templates/editpage.html b/docs/tools/_templates/ed= itpage.html
deleted file mode 100644
index 2a9c8fc92b..0000000000
--- a/docs/tools/_templates/editpage.html
+++ /dev/null
@@ -1,5 +0,0 @@
-<div id=3D"editpage">
-=C2=A0 <ul>
-=C2=A0 =C2=A0 <li><a href=3D"https://gitlab.com/qemu-project/qemu/-/blob/m= aster/docs/tools/{{pagename}}.rst">Page source</a></li= >
-=C2=A0 </ul>
-</div>
diff --git a/docs/user/_templates/editpage.html b/docs/user/_templates/edit= page.html
deleted file mode 100644
index 1f5ee01e60..0000000000
--- a/docs/user/_templates/editpage.html
+++ /dev/null
@@ -1,5 +0,0 @@
-<div id=3D"editpage">
-=C2=A0 <ul>
-=C2=A0 =C2=A0 <li><a href=3D"https://gitlab.com/qemu-project/qemu/-/blob/ma= ster/docs/user/{{pagename}}.rst">Page source</a></li&g= t;
-=C2=A0 </ul>
-</div>
diff --git a/tests/docker/dockerfiles/debian10.docker b/tests/docker/docker= files/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 && \
=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0psmisc \
=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0python3 \
=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0python3-sphinx \
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 python3-sphinx-rtd-theme \
=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0$(apt-get -s build-dep --arch-only qemu |= egrep ^Inst | fgrep '[all]' | cut -d\=C2=A0 -f2)

=C2=A0ENV FEATURES docs
diff --git a/tests/docker/dockerfiles/fedora.docker b/tests/docker/dockerfi= les/fedora.docker
index 915fdc1845..d8fa16372d 100644
--- a/tests/docker/dockerfiles/fedora.docker
+++ b/tests/docker/dockerfiles/fedora.docker
@@ -92,6 +92,7 @@ ENV PACKAGES \
=C2=A0 =C2=A0 =C2=A0python3-pillow \
=C2=A0 =C2=A0 =C2=A0python3-pip \
=C2=A0 =C2=A0 =C2=A0python3-sphinx \
+=C2=A0 =C2=A0 python3-sphinx_rtd_theme \
=C2=A0 =C2=A0 =C2=A0python3-virtualenv \
=C2=A0 =C2=A0 =C2=A0rdma-core-devel \
=C2=A0 =C2=A0 =C2=A0SDL2-devel \
diff --git a/tests/docker/dockerfiles/ubuntu.docker b/tests/docker/dockerfi= les/ubuntu.docker
index b5ef7a8198..98a527361c 100644
--- a/tests/docker/dockerfiles/ubuntu.docker
+++ b/tests/docker/dockerfiles/ubuntu.docker
@@ -63,6 +63,7 @@ ENV PACKAGES \
=C2=A0 =C2=A0 =C2=A0ninja-build \
=C2=A0 =C2=A0 =C2=A0python3-yaml \
=C2=A0 =C2=A0 =C2=A0python3-sphinx \
+=C2=A0 =C2=A0 python3-sphinx-rtd-theme \
=C2=A0 =C2=A0 =C2=A0sparse \
=C2=A0 =C2=A0 =C2=A0xfslibs-dev
=C2=A0RUN apt-get update && \
diff --git a/tests/docker/dockerfiles/ubuntu1804.docker b/tests/docker/dock= erfiles/ubuntu1804.docker
index 9b0a19ba5e..c0d3642507 100644
--- a/tests/docker/dockerfiles/ubuntu1804.docker
+++ b/tests/docker/dockerfiles/ubuntu1804.docker
@@ -48,6 +48,7 @@ ENV PACKAGES \
=C2=A0 =C2=A0 =C2=A0make \
=C2=A0 =C2=A0 =C2=A0python3-yaml \
=C2=A0 =C2=A0 =C2=A0python3-sphinx \
+=C2=A0 =C2=A0 python3-sphinx-rtd-theme \
=C2=A0 =C2=A0 =C2=A0ninja-build \
=C2=A0 =C2=A0 =C2=A0sparse \
=C2=A0 =C2=A0 =C2=A0xfslibs-dev
diff --git a/tests/docker/dockerfiles/ubuntu2004.docker b/tests/docker/dock= erfiles/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 \
=C2=A0 =C2=A0 =C2=A0python3-pil \
=C2=A0 =C2=A0 =C2=A0python3-pip \
=C2=A0 =C2=A0 =C2=A0python3-sphinx \
+=C2=A0 =C2=A0 python3-sphinx-rtd-theme \
=C2=A0 =C2=A0 =C2=A0python3-venv \
=C2=A0 =C2=A0 =C2=A0python3-yaml \
=C2=A0 =C2=A0 =C2=A0rpm2cpio \
--
2.29.0

--00000000000023193005be1df630--