Re: [PATCH v5] sphinx: adopt kernel readthedoc theme

[John Snow]

On 3/23/21 7:53 AM, 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 simplifies the "Edit on Gitlab" links.
>
> Tweak a bit the custom theme to match qemu.org style, use the
> QEMU logo, and favicon etc.
>
> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> Tested-by: Bin Meng <bmeng.cn@gmail.com>

Looks good in my opinion! I think it's definitely simpler to not try and 
maintain two themes to mixed results.

Reviewed-by: John Snow <jsnow@redhat.com>

> ---
> v5:
>   - raise an error if rtd theme is missing (also at configure time)
>   - commit message tweaks
>
>   docs/_templates/editpage.html              |   5 -
>   docs/conf.py                               |  51 ++++---
>   docs/devel/_templates/editpage.html        |   5 -
>   docs/interop/_templates/editpage.html      |   5 -
>   docs/meson.build                           |   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 +
>   15 files changed, 198 insertions(+), 59 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..3802b70d62 100644
> --- a/docs/conf.py
> +++ b/docs/conf.py
> @@ -150,38 +150,47 @@
>   # 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
> +except ImportError:
> +    raise ConfigError(
> +        'The Sphinx \'sphinx_rtd_theme\' HTML theme was not found.\n'
> +    )
> +
> +html_theme = 'sphinx_rtd_theme'
>   

Try using ModuleNotFoundError here, just in case. ImportError will also 
catch stuff like when the module *is* found, but breaks for other 
reasons, and may obscure the underlying reason, depending.

(Don't worry about it if there's no reason to re-spin, though, I think 
it's an extremely minor point. My RB is with or without the change.)

--js


Off-topic: Do you know how we go about enabling the version drop-down on 
the RTD site so we can refer back to older documents?