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

[John Snow <jsnow@redhat.com>]

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)