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

[Daniel P . Berrangé]

On Tue, Mar 23, 2021 at 11:00:29AM +0000, Peter Maydell wrote:
> 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 ?

The theme is pre-packaged for Fedora, Debian, Ubuntu, which gives me
confidence for Linux distros in general.

BSD / macOS / Windows, who knows ?

We could check for rtd theme in meson, and disable the docs build
if missing.  Might be better than pretending to have alabaster
fallback which none of us will ever test, and then get bugs about
it.


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