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

[Peter Maydell <peter.maydell@linaro.org>]

On Tue, 23 Mar 2021 at 10:27, 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.

> >  # 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 ?

How much do we want to retain support for multiple themes? When
I was first putting in the Sphinx documentation I found that some
things were kind of theme-specific, in that tweaking things to look
and read sensibly in one theme made them look a bit weird in another.
If we said "we support only the rtd theme and mandate it" would that
cause much pain for downstreams and end-users ?

thanks
-- PMM