[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH v3] sphinx: adopt kernel readthedoc theme
From: |
Marc-André Lureau |
Subject: |
Re: [PATCH v3] sphinx: adopt kernel readthedoc theme |
Date: |
Mon, 25 Jan 2021 23:31:37 +0400 |
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