Hi

On Tue, Mar 23, 2021 at 2:28 PM Daniel P. Berrangé <berrange@redhat.com>
wrote:

> On Mon, Mar 22, 2021 at 02:52:34PM +0400, 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.
>
> 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-documentation-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é 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',
> > +]
>
> 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 = {
> > +    "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 = {
> > -    '**': [
> > -        '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 = {}
> >
> >  # 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 :|
>
>
>

-- 
Marc-André Lureau