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=-14.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,HTML_MESSAGE,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,MENTIONS_GIT_HOSTING,SPF_HELO_NONE,SPF_PASS 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 D216AC433C1 for ; Tue, 23 Mar 2021 11:07:16 +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 42E2D619B8 for ; Tue, 23 Mar 2021 11:07:16 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 42E2D619B8 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=gmail.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:50108 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lOesV-00082r-9s for qemu-devel@archiver.kernel.org; Tue, 23 Mar 2021 07:07:15 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:50020) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lOerY-0007Rf-CG for qemu-devel@nongnu.org; Tue, 23 Mar 2021 07:06:17 -0400 Received: from mail-ej1-x635.google.com ([2a00:1450:4864:20::635]:41582) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1lOerU-0002It-3g for qemu-devel@nongnu.org; Tue, 23 Mar 2021 07:06:16 -0400 Received: by mail-ej1-x635.google.com with SMTP id u5so26380587ejn.8 for ; Tue, 23 Mar 2021 04:06:10 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=OWB9A4SkWhtJFDlNnWCWguLmnF5sygzciQDTOHHipQA=; b=nP1JsCQECMicQ1kb2HcAgUr53LIDt+QBzaIeKZWZ29mm54f/RorowKeEfAD2WrkFoV Q34xOBt+hLY+C7aVQLAJ/eyUYuKpGXKn7gloL1c6RaTjamZK8pvJg0nxnPfFVVZmZnrZ bVCoinWVTCj9FnYTzmpBvntqwOgfnRtZV2iNMt+3t8v7qq9bBI518AJD8hRGzlQNJkez CuOlfZuZAEWBKwkWNilY9JHuLqtG0r12BT2NCdIeyuV6zO2entAnVIZkbhzyTVyV/DEK SzUynI6duUvHrshbkZI605dmwkwL6ecrZGIKxqD8G6NpHhmj1n2lbDe2BHl8Bpp4FZNJ z+sg== 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=OWB9A4SkWhtJFDlNnWCWguLmnF5sygzciQDTOHHipQA=; b=glpVj5jqM/Pptpa1Qj1TD6b6/it8aZh9hcFt89Dn354ZW/pNp/fHutJTBRaYguLzmJ PTtQks36Fuhy7quYsrEjWBonmmETiNemdKsh6RXk8hqMUXpN7Dw0sg3FPEFYmDtZQ1FM do/YKeJs3TYehVyJmWnGLOA5hr2PMDwIvWjsPE9GdSLVAMqjfZ8VNxxziDDLJ+sefO4d RombsXEqbtjhmNxbfwrFv4fEGrv72Et4fVFQ0s+0CwwUW60BdzPAWV626ffLgLgIXXcC GPfnPEPuitxQTZDotLcju7qb3Ne0vp/cn6CNOkfb8REIPqpN1m1gSD1Cm5sUt8bYHrqA TuSQ== X-Gm-Message-State: AOAM532Jc2BTs4RvF49QJip//RYeszxHD66cYfSzeOMXJfaNC1Vz5EXd XjkSrdzh1/8N+cLJ1UPhpGwmPZDcmaNVPO2v+OE= X-Google-Smtp-Source: ABdhPJzBqhhfecDmlTpyjqm4rHDcPM1HzYVOLDJ7d6CXoX8K5uRy8r96PaCGuNRmN4fJP/YNJFYGRw2PytUjpYopEWU= X-Received: by 2002:a17:906:4e99:: with SMTP id v25mr4355207eju.532.1616497569949; Tue, 23 Mar 2021 04:06:09 -0700 (PDT) MIME-Version: 1.0 References: <20210322105234.3932691-1-marcandre.lureau@redhat.com> In-Reply-To: From: =?UTF-8?B?TWFyYy1BbmRyw6kgTHVyZWF1?= Date: Tue, 23 Mar 2021 15:05:57 +0400 Message-ID: Subject: Re: [PATCH v4] sphinx: adopt kernel readthedoc theme To: =?UTF-8?Q?Daniel_P=2E_Berrang=C3=A9?= Content-Type: multipart/alternative; boundary="0000000000006fed6005be322bcf" Received-SPF: pass client-ip=2a00:1450:4864:20::635; envelope-from=marcandre.lureau@gmail.com; helo=mail-ej1-x635.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, HTML_MESSAGE=0.001, RCVD_IN_DNSWL_NONE=-0.0001, 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: Peter Maydell , bmeng.cn@gmail.com, John Snow , QEMU Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" --0000000000006fed6005be322bcf Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Hi On Tue, Mar 23, 2021 at 2:28 PM Daniel P. Berrang=C3=A9 wrote: > On Mon, Mar 22, 2021 at 02:52:34PM +0400, marcandre.lureau@redhat.com > 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 use= d > > notably by the kernel, with a custom style sheet. I like it better, > > perhaps others do too. It also simplify "Edit on Gitlab" links. > > s/simplify/simplifies the/ > > ok > > > 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 > > I'd drop this from the commit message unless you're confident > this link will remain alive indefinitely. > No, I'll drop it. > > > > 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.html > > 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', > > +] > > Does this still have a good result in the case where we fall back > to alabaster theme ? > Yes (I can't see much difference) > > + > > +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 > names > > # 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', > > - ] > > -} > > Aren't these still needed when we fall back to the alabaster theme ? > No difference with the default for me. > Well the editpage.html can be dropped without real harm, but the > navigation.html looks pretty important to me. > > > +#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. > > > > > Regards, > Daniel > -- > |: https://berrange.com -o- > https://www.flickr.com/photos/dberrange :| > |: https://libvirt.org -o- > https://fstop138.berrange.com :| > |: https://entangle-photo.org -o- > https://www.instagram.com/dberrange :| > > > --=20 Marc-Andr=C3=A9 Lureau --0000000000006fed6005be322bcf Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
Hi

On Tue, Mar 23, 2021 at 2:28 PM Dan= iel P. Berrang=C3=A9 <berrange@re= dhat.com> wrote:
On Mon, Mar 22, 2021 at 02:52:34PM +0400, marcandre.lureau@redhat.com wro= te:
> From: Marc-Andr=C3=A9 Lureau <marcandre.lureau@redhat.com>
>
> The default "alabaster" sphinx theme has a couple shortcomin= gs:
> - 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 pa= rty 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" lin= ks.

s/simplify/simplifies the/


ok

>
> 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-docu= mentation-QEMU-documentation.png

I'd drop this from the commit message unless you're confident
this link will remain alive indefinitely.

No, I'll drop it.


>
> 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=A0 docs/_templates/editpage.html=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0 |=C2=A0 =C2=A05 -
>=C2=A0 docs/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=A0 docs/devel/_templates/editpage.html=C2=A0 =C2=A0 =C2=A0 =C2=A0 |= =C2=A0 =C2=A05 -
>=C2=A0 docs/interop/_templates/editpage.html=C2=A0 =C2=A0 =C2=A0 |=C2= =A0 =C2=A05 -
>=C2=A0 docs/specs/_templates/editpage.html=C2=A0 =C2=A0 =C2=A0 =C2=A0 |= =C2=A0 =C2=A05 -
>=C2=A0 docs/sphinx-static/theme_overrides.css=C2=A0 =C2=A0 =C2=A0| 161 = +++++++++++++++++++++
>=C2=A0 docs/system/_templates/editpage.html=C2=A0 =C2=A0 =C2=A0 =C2=A0|= =C2=A0 =C2=A05 -
>=C2=A0 docs/tools/_templates/editpage.html=C2=A0 =C2=A0 =C2=A0 =C2=A0 |= =C2=A0 =C2=A05 -
>=C2=A0 docs/user/_templates/editpage.html=C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0|=C2=A0 =C2=A05 -
>=C2=A0 tests/docker/dockerfiles/debian10.docker=C2=A0 =C2=A0|=C2=A0 =C2= =A01 +
>=C2=A0 tests/docker/dockerfiles/fedora.docker=C2=A0 =C2=A0 =C2=A0|=C2= =A0 =C2=A01 +
>=C2=A0 tests/docker/dockerfiles/ubuntu.docker=C2=A0 =C2=A0 =C2=A0|=C2= =A0 =C2=A01 +
>=C2=A0 tests/docker/dockerfiles/ubuntu1804.docker |=C2=A0 =C2=A01 +
>=C2=A0 tests/docker/dockerfiles/ubuntu2004.docker |=C2=A0 =C2=A01 +
>=C2=A0 14 files changed, 196 insertions(+), 55 deletions(-)
>=C2=A0 delete mode 100644 docs/_templates/editpage.html
>=C2=A0 delete mode 100644 docs/devel/_templates/editpage.html
>=C2=A0 delete mode 100644 docs/interop/_templates/editpage.html
>=C2=A0 delete mode 100644 docs/specs/_templates/editpage.html
>=C2=A0 create mode 100644 docs/sphinx-static/theme_overrides.css
>=C2=A0 delete mode 100644 docs/system/_templates/editpage.html
>=C2=A0 delete mode 100644 docs/tools/_templates/editpage.html
>=C2=A0 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=3D"editpage">
> -=C2=A0 <ul>
> -=C2=A0 =C2=A0 <li><a href=3D"https://gitlab.com/qemu-project/qemu/-/blob/ma= ster/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=A0 html_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= _theme\' HTML theme was not found. '
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 'Make sure you have the theme install= ed to produce pretty HTML '
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 'output. Falling back to the default = theme.\n')
>=C2=A0
>=C2=A0 # Theme options are theme-specific and customize the look and fe= el 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 jus= t
> -# 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_128x12= 8.png")
> +
> +html_favicon =3D os.path.join(qemu_docdir, "../ui/icons/qemu_32x= 32.png")
>=C2=A0
>=C2=A0 # Add any paths that contain custom static files (such as style = sheets) here,
>=C2=A0 # relative to this directory. They are copied after the builtin = static files,
>=C2=A0 # so a file named "default.css" will overwrite the bui= ltin "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&q= uot;)]
> +
> +html_css_files =3D [
> +=C2=A0 =C2=A0 'theme_overrides.css',
> +]

Does this still have a good result in the case where we fall back
to alabaster theme ?

Yes (I can't s= ee much difference)


> +
> +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
>=C2=A0 # Custom sidebar templates, must be a dictionary that maps docum= ent names
>=C2=A0 # to template names.
> -#
> -# This is required for the alabaster theme
> -# refs: http://alabaster.r= eadthedocs.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 ]
> -}

Aren't these still needed when we fall back to the alabaster theme ?

No difference with the default for me.


Well the editpage.html can be dropped without real harm, but the
navigation.html looks pretty important to me.

> +#html_sidebars =3D {}
>=C2=A0
>=C2=A0 # Don't copy the rST source files to the HTML output directo= ry,
>=C2=A0 # and don't put links to the sources into the output HTML.



Regards,
Daniel
--
|: ht= tps://berrange.com=C2=A0 =C2=A0 =C2=A0 -o-=C2=A0 =C2=A0 h= ttps://www.flickr.com/photos/dberrange :|
|: htt= ps://libvirt.org=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0-o-=C2=A0 =C2=A0 =C2= =A0 =C2=A0 =C2=A0 =C2=A0 https://fstop138.berrange.com :|
|: https://entangle-photo.org=C2=A0 =C2=A0 -o-=C2=A0 =C2=A0 = https://www.instagram.com/dberrange :|




--
Marc-Andr=C3=A9 Lureau
--0000000000006fed6005be322bcf--