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="" href="https://gitlab.com/qemu-project/qemu/-/blob/master/docs/%7B%7Bpagename%7D%7D.rst" rel="noreferrer" target="_blank">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 :|