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 C326FC433DB for ; Mon, 22 Mar 2021 11:36:05 +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 1F2876198E for ; Mon, 22 Mar 2021 11:36:05 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 1F2876198E 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]:37164 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lOIqq-00085e-8q for qemu-devel@archiver.kernel.org; Mon, 22 Mar 2021 07:36:04 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:52428) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lOIpY-0006qQ-VA for qemu-devel@nongnu.org; Mon, 22 Mar 2021 07:34:45 -0400 Received: from us-smtp-delivery-124.mimecast.com ([63.128.21.124]:24076) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1lOIpV-0002n5-2T for qemu-devel@nongnu.org; Mon, 22 Mar 2021 07:34:44 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1616412880; 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=/cdRpnFHJpz7FJDY8ZSGGfnOpDgLK6uKp4d26LfVFaQ=; b=QKnT3tDxqkvKxSvqKmQt0QlNgnTkOxU5gQp3B1Ihkx10USK+bYPrXxfBERY+kb4zhvYze3 M5g6Y/UiAF5vLklumbynVTcUv5BCwJSMV/yoiAEm5pMVRkkDKf1Wn1L8uFnxmjFbeZMuXu zwIgKIzNs95VDUmAf+hd//DUTdbdaG0= Received: from mail-il1-f198.google.com (mail-il1-f198.google.com [209.85.166.198]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-576-NBuROBiSOk2brAJrdx9TVA-1; Mon, 22 Mar 2021 07:34:36 -0400 X-MC-Unique: NBuROBiSOk2brAJrdx9TVA-1 Received: by mail-il1-f198.google.com with SMTP id s12so39450362ilh.20 for ; Mon, 22 Mar 2021 04:34:36 -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=/cdRpnFHJpz7FJDY8ZSGGfnOpDgLK6uKp4d26LfVFaQ=; b=NiThd0ae6hynAt7D8OVMmfm0/Ce8+hHdX+pgYQQ24Jd/r1QWE/yX83SRabMvoE29Fz F3U0IDGZoLp2gB3yZXD2+MSsGAAg8UXbbRUfmr2ohDwrpBPcNlJXzsHlwxq6Xc+4DY0w WfNlMKhAiLji5YU4UYnKd6RdNaXdm4eT3oVNNMBQW5lYMggCuleKYyhvk6m64XgLdaVf HBaQW/O2IZcbKDCLV9lpz9hwK5hAqL6GNpEMxHvrH8gEDgEImre8dmXxekAOnaDbBq3F CToMS9NU9DDUk+FT3KhqQPgc5d2VtOhQduSSv20M/JoADg0MYwSgQpox6zWHzQ3X+dkM +KVw== X-Gm-Message-State: AOAM531nTGY/iutEfWEfuY/K71V3utCCQ04CExxPpyvia/C4pVH86GJY 3SntAjPwTQADoCGUCTVQuzkamu4WfR0n+rQAlySo+C/TUU7UI3Qlsl51onQtPlpWgkTQ6Y/v+11 ajG8ba2Q9/arjX1/sAFoMldvhOPd66UU= X-Received: by 2002:a02:c610:: with SMTP id i16mr10905658jan.36.1616412875659; Mon, 22 Mar 2021 04:34:35 -0700 (PDT) X-Google-Smtp-Source: ABdhPJwsM1CJfeeVL44L5SDmDzFn4dsbHSldEXIk0C1xmgE8FW/rARBEriast/p+gpDYgftggUF6sY2ts2BA/JZ1FuI= X-Received: by 2002:a02:c610:: with SMTP id i16mr10905639jan.36.1616412875427; Mon, 22 Mar 2021 04:34:35 -0700 (PDT) MIME-Version: 1.0 References: <20210322105234.3932691-1-marcandre.lureau@redhat.com> In-Reply-To: From: =?UTF-8?B?TWFyYy1BbmRyw6kgTHVyZWF1?= Date: Mon, 22 Mar 2021 15:34:23 +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="000000000000401a3705be1e7380" Received-SPF: pass client-ip=63.128.21.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.001, RCVD_IN_MSPIKE_WL=0.001, 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" --000000000000401a3705be1e7380 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable On Mon, Mar 22, 2021 at 2:59 PM Marc-Andr=C3=A9 Lureau < marcandre.lureau@redhat.com> wrote: > 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-documen= tation-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%20Q= EMU%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%20QEM= U%e2%80%99s%20documentation%20%e2%80%94%20QEMU%20documentation(1).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.ht= ml >> 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 nam= es >> # 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 >> line 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 w= e >> 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 >> >> --000000000000401a3705be1e7380 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable


=
On Mon, Mar 22, 2021 at 2:59 PM Marc-= Andr=C3=A9 Lureau <marcan= dre.lureau@redhat.com> wrote:
Hi

On Mon, Mar 22, 2021 at 2:= 52 PM <= marcandre.lureau@redhat.com> wrote:
From: Marc-Andr=C3=A9 Lureau <marcandre.lureau@redhat.c= om>

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:


Wh= at about simplifying the various section titles?
=


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

--000000000000401a3705be1e7380--