Hi On Mon, Jan 25, 2021 at 8:47 PM John Snow <js...@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 <js...@redhat.com> wrote: > >> > >> On 1/20/21 5:25 AM, marcandre.lur...@redhat.com wrote: > >>> From: Marc-André Lureau <marcandre.lur...@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.lur...@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
