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

[Marc-André Lureau]

Hi

On Mon, Jan 25, 2021 at 8:47 PM John Snow <jsnow@redhat.com> wrote:
>
> On 1/24/21 1:19 PM, Marc-André Lureau wrote:
> > Hi
> >
> > On Fri, Jan 22, 2021 at 12:59 AM John Snow <jsnow@redhat.com> wrote:
> >>
> >> On 1/20/21 5:25 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 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                               |  47 +++---
> >>>    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, 193 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..5ee577750b 100644
> >>> --- a/docs/conf.py
> >>> +++ b/docs/conf.py
> >>> @@ -151,37 +151,44 @@ with open(os.path.join(qemu_docdir, 
> >>> 'defs.rst.inc')) as f:
> >>>    # 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",
> >>> +    }
> >>> +
> >>
> >> This needs a default for html_theme_options so that if sphinx_rtd_theme
> >> isn't present, the build doesn't break when using the fallback to
> >> alabaster; I'm seeing:
> >>
> >> Traceback (most recent call last):
> >>     File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 361,
> >> in eval_config_file
> >>       execfile_(filename, namespace)
> >>     File "/usr/lib/python3.8/site-packages/sphinx/util/pycompat.py", line
> >> 81, in execfile_
> >>       exec(code, _globals)
> >>     File "/home/jsnow/src/qemu/docs/user/conf.py", line 15, in <module>
> >>       html_theme_options['description'] = u'User Mode Emulation User''s
> >> Guide'
> >> NameError: name 'html_theme_options' is not defined
> >>
> >
> > Ok, I don't get that error with sphinx 3.2.1 on fc33...
> >
>
> Just in case it helps you:
>
> - FC33
> - Sphinx 3.4.3
> - alabaster 0.7.12
> - Python 3.9.1 (3.9.1-1.fc33)
>
> Hopefully we can just switch over to RTD theme and ignore the fallback,
> but you'll probably need to come up with a test matrix for sphinx
> versions and RTD theme versions and ensure that it works on our
> supported distro list.
>
> Variables:
> - Python versions (3.6 through 3.9)
> - Sphinx versions (?? through 3.4.3)
> - sphinx-rtd-theme vesrions (?? through 0.5.1)

Well it depends if we consider the sphinx documentation as a
first-class product that must build on all the systems we support.
When sphinx dependency was added, I don't think we did a thorough
check on where it was available and ensuring it builds properly on all
those systems. It's a bit unfair to ask that now just for the
rtd-theme.

That patch already checks debian/fedora/ubuntu (all the dockerfiles
where python-sphinx was installed already)

(quoting myself from earlier)
Peter (and others), do you have an opinion about whether we should
support the fallback/default theme?

Given that RTD is the kernel theme, it seems widely available:
https://repology.org/project/python:sphinx-rtd-theme/versions.

I can update the patch to check if the sphinx_rtd_theme module is
present, and error during configure time.

thanks