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)
