Re: [PATCH v2] RFC: sphinx: adopt kernel readthedoc theme

[Daniel P . Berrangé]

On Wed, Jan 20, 2021 at 11:41:02AM +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.
> 
> 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
> 
> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> ---
>  docs/_templates/editpage.html          |   5 -
>  docs/conf.py                           |  43 ++++---
>  docs/devel/_templates/editpage.html    |   5 -
>  docs/interop/_templates/editpage.html  |   5 -
>  docs/specs/_templates/editpage.html    |   5 -
>  docs/sphinx-static/theme_overrides.css | 157 +++++++++++++++++++++++++
>  docs/system/_templates/editpage.html   |   5 -
>  docs/tools/_templates/editpage.html    |   5 -
>  docs/user/_templates/editpage.html     |   5 -
>  9 files changed, 181 insertions(+), 54 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..2d9e8148a9 100644
> --- a/docs/conf.py
> +++ b/docs/conf.py
> @@ -150,38 +150,43 @@ with open(os.path.join(qemu_docdir, 'defs.rst.inc')) as 
> f:
>  # The theme to use for HTML and HTML Help pages.  See the documentation for
>  # 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')

Shouldn't we be keeping the html_theme = 'alabaster' to setup the
default theme for fallback ?


Also is this 'rtd' theme packaged in the various distros ? We will need it
added to the package lists in the dockerfiles so it is present for people
by default. Also we'll soon be publishing docs from GitLab CI jobs, so
will need the package in the dockerfiles to make it apply to the live
website.

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 :|