Hi On Tue, Mar 23, 2021 at 3:01 PM Peter Maydell wrote: > On Tue, 23 Mar 2021 at 10:27, Daniel P. Berrangé > wrote: > > > > On Mon, Mar 22, 2021 at 02:52:34PM +0400, marcandre.lureau@redhat.com > wrote: > > > From: Marc-André Lureau > > > > > > 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 ? > I don't expect it to be a problem: with this patch, we have the same requirement as the kernel: rtd is the default supported theme, alabaster is a fallback (with the minor styles hiccups/incompatibilities it may have) -- Marc-André Lureau