docs/_templates/editpage.html | 5 - docs/conf.py | 51 ++++--- docs/devel/_templates/editpage.html | 5 - docs/interop/_templates/editpage.html | 5 - docs/meson.build | 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 + 15 files changed, 198 insertions(+), 59 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
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 simplifies the "Edit on Gitlab" links.
Tweak a bit the custom theme to match qemu.org style, use the
QEMU logo, and favicon etc.
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Tested-by: Bin Meng <bmeng.cn@gmail.com>
---
v5:
- raise an error if rtd theme is missing (also at configure time)
- commit message tweaks
docs/_templates/editpage.html | 5 -
docs/conf.py | 51 ++++---
docs/devel/_templates/editpage.html | 5 -
docs/interop/_templates/editpage.html | 5 -
docs/meson.build | 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 +
15 files changed, 198 insertions(+), 59 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..3802b70d62 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -150,38 +150,47 @@
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
-html_theme = 'alabaster'
+try:
+ import sphinx_rtd_theme
+except ImportError:
+ raise ConfigError(
+ 'The Sphinx \'sphinx_rtd_theme\' HTML theme was not found.\n'
+ )
+
+html_theme = 'sphinx_rtd_theme'
# 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",
+ }
+
+html_logo = os.path.join(qemu_docdir, "../ui/icons/qemu_128x128.png")
+
+html_favicon = os.path.join(qemu_docdir, "../ui/icons/qemu_32x32.png")
# 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',
+]
+
+html_context = {
+ "display_gitlab": True,
+ "gitlab_user": "qemu-project",
+ "gitlab_repo": "qemu",
+ "gitlab_version": "master",
+ "conf_py_path": "/docs/", # Path in the checkout to the docs root
+}
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
-#
-# This is required for the alabaster theme
-# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
-html_sidebars = {
- '**': [
- 'about.html',
- 'editpage.html',
- 'navigation.html',
- 'searchbox.html',
- ]
-}
+#html_sidebars = {}
# Don't copy the rST source files to the HTML output directory,
# and don't put links to the sources into the output HTML.
diff --git a/docs/devel/_templates/editpage.html b/docs/devel/_templates/editpage.html
deleted file mode 100644
index a86d22bca8..0000000000
--- a/docs/devel/_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/devel/{{pagename}}.rst">Page source</a></li>
- </ul>
-</div>
diff --git a/docs/interop/_templates/editpage.html b/docs/interop/_templates/editpage.html
deleted file mode 100644
index 215e562681..0000000000
--- a/docs/interop/_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/interop/{{pagename}}.rst">Page source</a></li>
- </ul>
-</div>
diff --git a/docs/meson.build b/docs/meson.build
index f84306ba7e..855e3916e9 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -27,10 +27,9 @@ if sphinx_build.found()
build_docs = (sphinx_build_test_out.returncode() == 0)
if not build_docs
- warning('@0@ is either too old or uses too old a Python version'
- .format(sphinx_build.full_path()))
+ warning('@0@: @1@'.format(sphinx_build.full_path(), sphinx_build_test_out.stderr()))
if get_option('docs').enabled()
- error('Install a Python 3 version of python-sphinx')
+ error('Install a Python 3 version of python-sphinx and the readthedoc theme')
endif
endif
endif
diff --git a/docs/specs/_templates/editpage.html b/docs/specs/_templates/editpage.html
deleted file mode 100644
index aaa468aa98..0000000000
--- a/docs/specs/_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/specs/{{pagename}}.rst">Page source</a></li>
- </ul>
-</div>
diff --git a/docs/sphinx-static/theme_overrides.css b/docs/sphinx-static/theme_overrides.css
new file mode 100644
index 0000000000..c70ef95128
--- /dev/null
+++ b/docs/sphinx-static/theme_overrides.css
@@ -0,0 +1,161 @@
+/* -*- coding: utf-8; mode: css -*-
+ *
+ * Sphinx HTML theme customization: read the doc
+ * Based on Linux Documentation/sphinx-static/theme_overrides.css
+ */
+
+/* Improve contrast and increase size for easier reading. */
+
+body {
+ font-family: serif;
+ color: black;
+ font-size: 100%;
+}
+
+h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend {
+ font-family: sans-serif;
+}
+
+.rst-content dl:not(.docutils) dt {
+ border-top: none;
+ border-left: solid 3px #ccc;
+ background-color: #f0f0f0;
+ color: black;
+}
+
+.wy-nav-top {
+ background: #802400;
+}
+
+.wy-side-nav-search input[type="text"] {
+ border-color: #f60;
+}
+
+.wy-menu-vertical p.caption {
+ color: white;
+}
+
+.wy-menu-vertical li.current a {
+ color: #505050;
+}
+
+.wy-menu-vertical li.on a, .wy-menu-vertical li.current > a {
+ color: #303030;
+}
+
+.fa-gitlab {
+ box-shadow: 0 4px 8px 0 rgba(0,0,0,0.2), 0 3px 10px 0 rgba(0,0,0,0.19);
+ border-radius: 5px;
+}
+
+div[class^="highlight"] pre {
+ font-family: monospace;
+ color: black;
+ font-size: 100%;
+}
+
+.wy-menu-vertical {
+ font-family: sans-serif;
+}
+
+.c {
+ font-style: normal;
+}
+
+p {
+ font-size: 100%;
+}
+
+/* Interim: Code-blocks with line nos - lines and line numbers don't line up.
+ * see: https://github.com/rtfd/sphinx_rtd_theme/issues/419
+ */
+
+div[class^="highlight"] pre {
+ line-height: normal;
+}
+.rst-content .highlight > pre {
+ line-height: normal;
+}
+
+/* Keep fields from being strangely far apart due to inheirited table CSS. */
+.rst-content table.field-list th.field-name {
+ padding-top: 1px;
+ padding-bottom: 1px;
+}
+.rst-content table.field-list td.field-body {
+ padding-top: 1px;
+ padding-bottom: 1px;
+}
+
+@media screen {
+
+ /* content column
+ *
+ * RTD theme's default is 800px as max width for the content, but we have
+ * tables with tons of columns, which need the full width of the view-port.
+ */
+
+ .wy-nav-content{max-width: none; }
+
+ /* table:
+ *
+ * - Sequences of whitespace should collapse into a single whitespace.
+ * - make the overflow auto (scrollbar if needed)
+ * - align caption "left" ("center" is unsuitable on vast tables)
+ */
+
+ .wy-table-responsive table td { white-space: normal; }
+ .wy-table-responsive { overflow: auto; }
+ .rst-content table.docutils caption { text-align: left; font-size: 100%; }
+
+ /* captions:
+ *
+ * - captions should have 100% (not 85%) font size
+ * - hide the permalink symbol as long as link is not hovered
+ */
+
+ .toc-title {
+ font-size: 150%;
+ font-weight: bold;
+ }
+
+ caption, .wy-table caption, .rst-content table.field-list caption {
+ font-size: 100%;
+ }
+ caption a.headerlink { opacity: 0; }
+ caption a.headerlink:hover { opacity: 1; }
+
+ /* Menu selection and keystrokes */
+
+ span.menuselection {
+ color: blue;
+ font-family: "Courier New", Courier, monospace
+ }
+
+ code.kbd, code.kbd span {
+ color: white;
+ background-color: darkblue;
+ font-weight: bold;
+ font-family: "Courier New", Courier, monospace
+ }
+
+ /* fix bottom margin of lists items */
+
+ .rst-content .section ul li:last-child, .rst-content .section ul li p:last-child {
+ margin-bottom: 12px;
+ }
+
+ /* inline literal: drop the borderbox, padding and red color */
+
+ code, .rst-content tt, .rst-content code {
+ color: inherit;
+ border: none;
+ padding: unset;
+ background: inherit;
+ font-size: 85%;
+ }
+
+ .rst-content tt.literal,.rst-content tt.literal,.rst-content code.literal {
+ color: inherit;
+ }
+}
diff --git a/docs/system/_templates/editpage.html b/docs/system/_templates/editpage.html
deleted file mode 100644
index 6586b2e257..0000000000
--- a/docs/system/_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/system/{{pagename}}.rst">Page source</a></li>
- </ul>
-</div>
diff --git a/docs/tools/_templates/editpage.html b/docs/tools/_templates/editpage.html
deleted file mode 100644
index 2a9c8fc92b..0000000000
--- a/docs/tools/_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/tools/{{pagename}}.rst">Page source</a></li>
- </ul>
-</div>
diff --git a/docs/user/_templates/editpage.html b/docs/user/_templates/editpage.html
deleted file mode 100644
index 1f5ee01e60..0000000000
--- a/docs/user/_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/user/{{pagename}}.rst">Page source</a></li>
- </ul>
-</div>
diff --git a/tests/docker/dockerfiles/debian10.docker b/tests/docker/dockerfiles/debian10.docker
index d034acbd25..63cf835ec5 100644
--- a/tests/docker/dockerfiles/debian10.docker
+++ b/tests/docker/dockerfiles/debian10.docker
@@ -32,6 +32,7 @@ RUN apt update && \
psmisc \
python3 \
python3-sphinx \
+ python3-sphinx-rtd-theme \
$(apt-get -s build-dep --arch-only qemu | egrep ^Inst | fgrep '[all]' | cut -d\ -f2)
ENV FEATURES docs
diff --git a/tests/docker/dockerfiles/fedora.docker b/tests/docker/dockerfiles/fedora.docker
index 915fdc1845..d8fa16372d 100644
--- a/tests/docker/dockerfiles/fedora.docker
+++ b/tests/docker/dockerfiles/fedora.docker
@@ -92,6 +92,7 @@ ENV PACKAGES \
python3-pillow \
python3-pip \
python3-sphinx \
+ python3-sphinx_rtd_theme \
python3-virtualenv \
rdma-core-devel \
SDL2-devel \
diff --git a/tests/docker/dockerfiles/ubuntu.docker b/tests/docker/dockerfiles/ubuntu.docker
index b5ef7a8198..98a527361c 100644
--- a/tests/docker/dockerfiles/ubuntu.docker
+++ b/tests/docker/dockerfiles/ubuntu.docker
@@ -63,6 +63,7 @@ ENV PACKAGES \
ninja-build \
python3-yaml \
python3-sphinx \
+ python3-sphinx-rtd-theme \
sparse \
xfslibs-dev
RUN apt-get update && \
diff --git a/tests/docker/dockerfiles/ubuntu1804.docker b/tests/docker/dockerfiles/ubuntu1804.docker
index 9b0a19ba5e..c0d3642507 100644
--- a/tests/docker/dockerfiles/ubuntu1804.docker
+++ b/tests/docker/dockerfiles/ubuntu1804.docker
@@ -48,6 +48,7 @@ ENV PACKAGES \
make \
python3-yaml \
python3-sphinx \
+ python3-sphinx-rtd-theme \
ninja-build \
sparse \
xfslibs-dev
diff --git a/tests/docker/dockerfiles/ubuntu2004.docker b/tests/docker/dockerfiles/ubuntu2004.docker
index 9750016e51..f1e0ebad49 100644
--- a/tests/docker/dockerfiles/ubuntu2004.docker
+++ b/tests/docker/dockerfiles/ubuntu2004.docker
@@ -58,6 +58,7 @@ ENV PACKAGES flex bison \
python3-pil \
python3-pip \
python3-sphinx \
+ python3-sphinx-rtd-theme \
python3-venv \
python3-yaml \
rpm2cpio \
--
2.29.0
On 23.03.21 12:53, marcandre.lureau@redhat.com wrote:
> From: Marc-André Lureau <marcandre.lureau@redhat.com>
>
Just saw this patch by accident and as we also use the alabaster theme
for the Proxmox Backup project I wanted to share some insights from our
usage, as I checked that theme out closely a few months ago and did some
adaptions for, partially overlapping, short-comings we found.
> The default "alabaster" sphinx theme has a couple shortcomings:
> - the navbar moves along the page
That can be fixed with the following conf.py 'html_theme_options' setting:
'fixed_sidebar': True,
https://git.proxmox.com/?p=proxmox-backup.git;a=blob;f=docs/conf.py;h=cfa4158d6b284172929785991f710d6237e9992c;hb=2ab2ca9c241f8315f51f9c74a50d7223c875a04b#l161
> - the search bar is not always at the same place
Can be also addressed by setting 'html_sidebars' to a fixed order, e.g.:
html_sidebars = {
'**': [
'searchbox.html',
'navigation.html',
'relations.html',
]
}
Can also be customized for different pages, e.g., we do so for landing pages:
https://git.proxmox.com/?p=proxmox-backup.git;a=blob;f=docs/conf.py;h=cfa4158d6b284172929785991f710d6237e9992c;hb=2ab2ca9c241f8315f51f9c74a50d7223c875a04b#l188
I added also a short JS snipped to scroll the heading of the current chapter in
the sidebar TOC into view (adapted from rust book).
https://git.proxmox.com/?p=proxmox-backup.git;a=blob;f=docs/custom.js;h=7964b2cb0ea9433596845618f1679f1672ce38b8;hb=2ab2ca9c241f8315f51f9c74a50d7223c875a04b
If you want, you could check out the result at our hosted docs site:
https://pbs.proxmox.com/docs/managing-remotes.html
> - it lacks some contrast and colours
That is true, and IMO the rtd theme really uses a better colour palette,
especially for things like "Topic" blocks.
In fact we pondered switching over to rtd, so please don't see my mail
as me advertising that all issues can be fixed into alabaster, just wanted
to share what we did to overcome the first two short-comings mentioned here.
cheers,
Thomas
Hi
On Tue, Mar 23, 2021 at 4:27 PM Thomas Lamprecht <t.lamprecht@proxmox.com>
wrote:
> On 23.03.21 12:53, marcandre.lureau@redhat.com wrote:
> > From: Marc-André Lureau <marcandre.lureau@redhat.com>
> >
>
> Just saw this patch by accident and as we also use the alabaster theme
> for the Proxmox Backup project I wanted to share some insights from our
> usage, as I checked that theme out closely a few months ago and did some
> adaptions for, partially overlapping, short-comings we found.
>
>
> > The default "alabaster" sphinx theme has a couple shortcomings:
> > - the navbar moves along the page
>
> That can be fixed with the following conf.py 'html_theme_options' setting:
>
> 'fixed_sidebar': True,
>
>
> https://git.proxmox.com/?p=proxmox-backup.git;a=blob;f=docs/conf.py;h=cfa4158d6b284172929785991f710d6237e9992c;hb=2ab2ca9c241f8315f51f9c74a50d7223c875a04b#l161
>
> > - the search bar is not always at the same place
>
> Can be also addressed by setting 'html_sidebars' to a fixed order, e.g.:
>
> html_sidebars = {
> '**': [
> 'searchbox.html',
> 'navigation.html',
> 'relations.html',
> ]
> }
>
> Can also be customized for different pages, e.g., we do so for landing
> pages:
>
>
> https://git.proxmox.com/?p=proxmox-backup.git;a=blob;f=docs/conf.py;h=cfa4158d6b284172929785991f710d6237e9992c;hb=2ab2ca9c241f8315f51f9c74a50d7223c875a04b#l188
>
> I added also a short JS snipped to scroll the heading of the current
> chapter in
> the sidebar TOC into view (adapted from rust book).
>
> https://git.proxmox.com/?p=proxmox-backup.git;a=blob;f=docs/custom.js;h=7964b2cb0ea9433596845618f1679f1672ce38b8;hb=2ab2ca9c241f8315f51f9c74a50d7223c875a04b
>
> If you want, you could check out the result at our hosted docs site:
> https://pbs.proxmox.com/docs/managing-remotes.html
Great, thanks for the tips.
However, the result doesn't seem as good on mobile yet.
>
> > - it lacks some contrast and colours
>
> That is true, and IMO the rtd theme really uses a better colour palette,
> especially for things like "Topic" blocks.
> In fact we pondered switching over to rtd, so please don't see my mail
> as me advertising that all issues can be fixed into alabaster, just wanted
> to share what we did to overcome the first two short-comings mentioned
> here.
>
Would you prefer QEMU to keep alabaster as a working and supported fallback
for consistency? or you could maintain a downstream patch for your version
perhaps?
--
Marc-André Lureau
Hi Thomas
On Tue, Mar 23, 2021 at 4:34 PM Marc-André Lureau <
marcandre.lureau@gmail.com> wrote:
> Hi
>
> On Tue, Mar 23, 2021 at 4:27 PM Thomas Lamprecht <t.lamprecht@proxmox.com>
> wrote:
>
>> On 23.03.21 12:53, marcandre.lureau@redhat.com wrote:
>> > From: Marc-André Lureau <marcandre.lureau@redhat.com>
>> >
>>
>> Just saw this patch by accident and as we also use the alabaster theme
>> for the Proxmox Backup project I wanted to share some insights from our
>> usage, as I checked that theme out closely a few months ago and did some
>> adaptions for, partially overlapping, short-comings we found.
>>
>>
>> > The default "alabaster" sphinx theme has a couple shortcomings:
>> > - the navbar moves along the page
>>
>> That can be fixed with the following conf.py 'html_theme_options' setting:
>>
>> 'fixed_sidebar': True,
>>
>>
>> https://git.proxmox.com/?p=proxmox-backup.git;a=blob;f=docs/conf.py;h=cfa4158d6b284172929785991f710d6237e9992c;hb=2ab2ca9c241f8315f51f9c74a50d7223c875a04b#l161
>>
>> > - the search bar is not always at the same place
>>
>> Can be also addressed by setting 'html_sidebars' to a fixed order, e.g.:
>>
>> html_sidebars = {
>> '**': [
>> 'searchbox.html',
>> 'navigation.html',
>> 'relations.html',
>> ]
>> }
>>
>> Can also be customized for different pages, e.g., we do so for landing
>> pages:
>>
>>
>> https://git.proxmox.com/?p=proxmox-backup.git;a=blob;f=docs/conf.py;h=cfa4158d6b284172929785991f710d6237e9992c;hb=2ab2ca9c241f8315f51f9c74a50d7223c875a04b#l188
>>
>> I added also a short JS snipped to scroll the heading of the current
>> chapter in
>> the sidebar TOC into view (adapted from rust book).
>>
>> https://git.proxmox.com/?p=proxmox-backup.git;a=blob;f=docs/custom.js;h=7964b2cb0ea9433596845618f1679f1672ce38b8;hb=2ab2ca9c241f8315f51f9c74a50d7223c875a04b
>>
>> If you want, you could check out the result at our hosted docs site:
>> https://pbs.proxmox.com/docs/managing-remotes.html
>
>
> Great, thanks for the tips.
>
> However, the result doesn't seem as good on mobile yet.
>
>
>>
>> > - it lacks some contrast and colours
>>
>> That is true, and IMO the rtd theme really uses a better colour palette,
>> especially for things like "Topic" blocks.
>> In fact we pondered switching over to rtd, so please don't see my mail
>> as me advertising that all issues can be fixed into alabaster, just wanted
>> to share what we did to overcome the first two short-comings mentioned
>> here.
>>
>
> Would you prefer QEMU to keep alabaster as a working and supported
> fallback for consistency? or you could maintain a downstream patch for your
> version perhaps?
>
>
Unless you have an objecting, I will proceed as discussed earlier, and
re-send patches to support only rtd theme.
thanks
--
Marc-André Lureau
On Tue, Mar 23, 2021 at 3:54 PM <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 simplifies the "Edit on Gitlab" links.
>
> Tweak a bit the custom theme to match qemu.org style, use the
> QEMU logo, and favicon etc.
>
> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> Tested-by: Bin Meng <bmeng.cn@gmail.com>
> ---
> v5:
> - raise an error if rtd theme is missing (also at configure time)
> - commit message tweaks
>
> docs/_templates/editpage.html | 5 -
> docs/conf.py | 51 ++++---
> docs/devel/_templates/editpage.html | 5 -
> docs/interop/_templates/editpage.html | 5 -
> docs/meson.build | 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 +
> 15 files changed, 198 insertions(+), 59 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
>
>
Ah I already sent that newer version, anybody to review/ack?
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..3802b70d62 100644
> --- a/docs/conf.py
> +++ b/docs/conf.py
> @@ -150,38 +150,47 @@
> # The theme to use for HTML and HTML Help pages. See the documentation
> for
> # a list of builtin themes.
> #
> -html_theme = 'alabaster'
> +try:
> + import sphinx_rtd_theme
> +except ImportError:
> + raise ConfigError(
> + 'The Sphinx \'sphinx_rtd_theme\' HTML theme was not found.\n'
> + )
> +
> +html_theme = 'sphinx_rtd_theme'
>
> # 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",
> + }
> +
> +html_logo = os.path.join(qemu_docdir, "../ui/icons/qemu_128x128.png")
> +
> +html_favicon = os.path.join(qemu_docdir, "../ui/icons/qemu_32x32.png")
>
> # 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',
> +]
> +
> +html_context = {
> + "display_gitlab": True,
> + "gitlab_user": "qemu-project",
> + "gitlab_repo": "qemu",
> + "gitlab_version": "master",
> + "conf_py_path": "/docs/", # Path in the checkout to the docs root
> +}
>
> # Custom sidebar templates, must be a dictionary that maps document names
> # to template names.
> -#
> -# This is required for the alabaster theme
> -# refs:
> http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
> -html_sidebars
> <http://alabaster.readthedocs.io/en/latest/installation.html#sidebars-html_sidebars>
> = {
> - '**': [
> - 'about.html',
> - 'editpage.html',
> - 'navigation.html',
> - 'searchbox.html',
> - ]
> -}
> +#html_sidebars = {}
>
> # Don't copy the rST source files to the HTML output directory,
> # and don't put links to the sources into the output HTML.
> diff --git a/docs/devel/_templates/editpage.html
> b/docs/devel/_templates/editpage.html
> deleted file mode 100644
> index a86d22bca8..0000000000
> --- a/docs/devel/_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/devel/{{pagename}}.rst">Page
> source</a></li>
> - </ul>
> -</div>
> diff --git a/docs/interop/_templates/editpage.html
> b/docs/interop/_templates/editpage.html
> deleted file mode 100644
> index 215e562681..0000000000
> --- a/docs/interop/_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/interop/{{pagename}}.rst">Page
> source</a></li>
> - </ul>
> -</div>
> diff --git a/docs/meson.build b/docs/meson.build
> index f84306ba7e..855e3916e9 100644
> --- a/docs/meson.build
> +++ b/docs/meson.build
> @@ -27,10 +27,9 @@ if sphinx_build.found()
> build_docs = (sphinx_build_test_out.returncode() == 0)
>
> if not build_docs
> - warning('@0@ is either too old or uses too old a Python version'
> - .format(sphinx_build.full_path()))
> + warning('@0@: @1@'.format(sphinx_build.full_path(),
> sphinx_build_test_out.stderr()))
> if get_option('docs').enabled()
> - error('Install a Python 3 version of python-sphinx')
> + error('Install a Python 3 version of python-sphinx and the
> readthedoc theme')
> endif
> endif
> endif
> diff --git a/docs/specs/_templates/editpage.html
> b/docs/specs/_templates/editpage.html
> deleted file mode 100644
> index aaa468aa98..0000000000
> --- a/docs/specs/_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/specs/{{pagename}}.rst">Page
> source</a></li>
> - </ul>
> -</div>
> diff --git a/docs/sphinx-static/theme_overrides.css
> b/docs/sphinx-static/theme_overrides.css
> new file mode 100644
> index 0000000000..c70ef95128
> --- /dev/null
> +++ b/docs/sphinx-static/theme_overrides.css
> @@ -0,0 +1,161 @@
> +/* -*- coding: utf-8; mode: css -*-
> + *
> + * Sphinx HTML theme customization: read the doc
> + * Based on Linux Documentation/sphinx-static/theme_overrides.css
> + */
> +
> +/* Improve contrast and increase size for easier reading. */
> +
> +body {
> + font-family: serif;
> + color: black;
> + font-size: 100%;
> +}
> +
> +h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend {
> + font-family: sans-serif;
> +}
> +
> +.rst-content dl:not(.docutils) dt {
> + border-top: none;
> + border-left: solid 3px #ccc;
> + background-color: #f0f0f0;
> + color: black;
> +}
> +
> +.wy-nav-top {
> + background: #802400;
> +}
> +
> +.wy-side-nav-search input[type="text"] {
> + border-color: #f60;
> +}
> +
> +.wy-menu-vertical p.caption {
> + color: white;
> +}
> +
> +.wy-menu-vertical li.current a {
> + color: #505050;
> +}
> +
> +.wy-menu-vertical li.on a, .wy-menu-vertical li.current > a {
> + color: #303030;
> +}
> +
> +.fa-gitlab {
> + box-shadow: 0 4px 8px 0 rgba(0,0,0,0.2), 0 3px 10px 0
> rgba(0,0,0,0.19);
> + border-radius: 5px;
> +}
> +
> +div[class^="highlight"] pre {
> + font-family: monospace;
> + color: black;
> + font-size: 100%;
> +}
> +
> +.wy-menu-vertical {
> + font-family: sans-serif;
> +}
> +
> +.c {
> + font-style: normal;
> +}
> +
> +p {
> + font-size: 100%;
> +}
> +
> +/* Interim: Code-blocks with line nos - lines and line numbers don't line
> up.
> + * see: https://github.com/rtfd/sphinx_rtd_theme/issues/419
> + */
> +
> +div[class^="highlight"] pre {
> + line-height: normal;
> +}
> +.rst-content .highlight > pre {
> + line-height: normal;
> +}
> +
> +/* Keep fields from being strangely far apart due to inheirited table
> CSS. */
> +.rst-content table.field-list th.field-name {
> + padding-top: 1px;
> + padding-bottom: 1px;
> +}
> +.rst-content table.field-list td.field-body {
> + padding-top: 1px;
> + padding-bottom: 1px;
> +}
> +
> +@media screen {
> +
> + /* content column
> + *
> + * RTD theme's default is 800px as max width for the content, but we
> have
> + * tables with tons of columns, which need the full width of the
> view-port.
> + */
> +
> + .wy-nav-content{max-width: none; }
> +
> + /* table:
> + *
> + * - Sequences of whitespace should collapse into a single
> whitespace.
> + * - make the overflow auto (scrollbar if needed)
> + * - align caption "left" ("center" is unsuitable on vast tables)
> + */
> +
> + .wy-table-responsive table td { white-space: normal; }
> + .wy-table-responsive { overflow: auto; }
> + .rst-content table.docutils caption { text-align: left; font-size:
> 100%; }
> +
> + /* captions:
> + *
> + * - captions should have 100% (not 85%) font size
> + * - hide the permalink symbol as long as link is not hovered
> + */
> +
> + .toc-title {
> + font-size: 150%;
> + font-weight: bold;
> + }
> +
> + caption, .wy-table caption, .rst-content table.field-list caption {
> + font-size: 100%;
> + }
> + caption a.headerlink { opacity: 0; }
> + caption a.headerlink:hover { opacity: 1; }
> +
> + /* Menu selection and keystrokes */
> +
> + span.menuselection {
> + color: blue;
> + font-family: "Courier New", Courier, monospace
> + }
> +
> + code.kbd, code.kbd span {
> + color: white;
> + background-color: darkblue;
> + font-weight: bold;
> + font-family: "Courier New", Courier, monospace
> + }
> +
> + /* fix bottom margin of lists items */
> +
> + .rst-content .section ul li:last-child, .rst-content .section ul li
> p:last-child {
> + margin-bottom: 12px;
> + }
> +
> + /* inline literal: drop the borderbox, padding and red color */
> +
> + code, .rst-content tt, .rst-content code {
> + color: inherit;
> + border: none;
> + padding: unset;
> + background: inherit;
> + font-size: 85%;
> + }
> +
> + .rst-content tt.literal,.rst-content tt.literal,.rst-content
> code.literal {
> + color: inherit;
> + }
> +}
> diff --git a/docs/system/_templates/editpage.html
> b/docs/system/_templates/editpage.html
> deleted file mode 100644
> index 6586b2e257..0000000000
> --- a/docs/system/_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/system/{{pagename}}.rst">Page
> source</a></li>
> - </ul>
> -</div>
> diff --git a/docs/tools/_templates/editpage.html
> b/docs/tools/_templates/editpage.html
> deleted file mode 100644
> index 2a9c8fc92b..0000000000
> --- a/docs/tools/_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/tools/{{pagename}}.rst">Page
> source</a></li>
> - </ul>
> -</div>
> diff --git a/docs/user/_templates/editpage.html
> b/docs/user/_templates/editpage.html
> deleted file mode 100644
> index 1f5ee01e60..0000000000
> --- a/docs/user/_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/user/{{pagename}}.rst">Page
> source</a></li>
> - </ul>
> -</div>
> diff --git a/tests/docker/dockerfiles/debian10.docker
> b/tests/docker/dockerfiles/debian10.docker
> index d034acbd25..63cf835ec5 100644
> --- a/tests/docker/dockerfiles/debian10.docker
> +++ b/tests/docker/dockerfiles/debian10.docker
> @@ -32,6 +32,7 @@ RUN apt update && \
> psmisc \
> python3 \
> python3-sphinx \
> + python3-sphinx-rtd-theme \
> $(apt-get -s build-dep --arch-only qemu | egrep ^Inst | fgrep
> '[all]' | cut -d\ -f2)
>
> ENV FEATURES docs
> diff --git a/tests/docker/dockerfiles/fedora.docker
> b/tests/docker/dockerfiles/fedora.docker
> index 915fdc1845..d8fa16372d 100644
> --- a/tests/docker/dockerfiles/fedora.docker
> +++ b/tests/docker/dockerfiles/fedora.docker
> @@ -92,6 +92,7 @@ ENV PACKAGES \
> python3-pillow \
> python3-pip \
> python3-sphinx \
> + python3-sphinx_rtd_theme \
> python3-virtualenv \
> rdma-core-devel \
> SDL2-devel \
> diff --git a/tests/docker/dockerfiles/ubuntu.docker
> b/tests/docker/dockerfiles/ubuntu.docker
> index b5ef7a8198..98a527361c 100644
> --- a/tests/docker/dockerfiles/ubuntu.docker
> +++ b/tests/docker/dockerfiles/ubuntu.docker
> @@ -63,6 +63,7 @@ ENV PACKAGES \
> ninja-build \
> python3-yaml \
> python3-sphinx \
> + python3-sphinx-rtd-theme \
> sparse \
> xfslibs-dev
> RUN apt-get update && \
> diff --git a/tests/docker/dockerfiles/ubuntu1804.docker
> b/tests/docker/dockerfiles/ubuntu1804.docker
> index 9b0a19ba5e..c0d3642507 100644
> --- a/tests/docker/dockerfiles/ubuntu1804.docker
> +++ b/tests/docker/dockerfiles/ubuntu1804.docker
> @@ -48,6 +48,7 @@ ENV PACKAGES \
> make \
> python3-yaml \
> python3-sphinx \
> + python3-sphinx-rtd-theme \
> ninja-build \
> sparse \
> xfslibs-dev
> diff --git a/tests/docker/dockerfiles/ubuntu2004.docker
> b/tests/docker/dockerfiles/ubuntu2004.docker
> index 9750016e51..f1e0ebad49 100644
> --- a/tests/docker/dockerfiles/ubuntu2004.docker
> +++ b/tests/docker/dockerfiles/ubuntu2004.docker
> @@ -58,6 +58,7 @@ ENV PACKAGES flex bison \
> python3-pil \
> python3-pip \
> python3-sphinx \
> + python3-sphinx-rtd-theme \
> python3-venv \
> python3-yaml \
> rpm2cpio \
> --
> 2.29.0
>
>
>
--
Marc-André Lureau
On 3/23/21 7:53 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 simplifies the "Edit on Gitlab" links.
>
> Tweak a bit the custom theme to match qemu.org style, use the
> QEMU logo, and favicon etc.
>
> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> Tested-by: Bin Meng <bmeng.cn@gmail.com>
Looks good in my opinion! I think it's definitely simpler to not try and
maintain two themes to mixed results.
Reviewed-by: John Snow <jsnow@redhat.com>
> ---
> v5:
> - raise an error if rtd theme is missing (also at configure time)
> - commit message tweaks
>
> docs/_templates/editpage.html | 5 -
> docs/conf.py | 51 ++++---
> docs/devel/_templates/editpage.html | 5 -
> docs/interop/_templates/editpage.html | 5 -
> docs/meson.build | 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 +
> 15 files changed, 198 insertions(+), 59 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..3802b70d62 100644
> --- a/docs/conf.py
> +++ b/docs/conf.py
> @@ -150,38 +150,47 @@
> # The theme to use for HTML and HTML Help pages. See the documentation for
> # a list of builtin themes.
> #
> -html_theme = 'alabaster'
> +try:
> + import sphinx_rtd_theme
> +except ImportError:
> + raise ConfigError(
> + 'The Sphinx \'sphinx_rtd_theme\' HTML theme was not found.\n'
> + )
> +
> +html_theme = 'sphinx_rtd_theme'
>
Try using ModuleNotFoundError here, just in case. ImportError will also
catch stuff like when the module *is* found, but breaks for other
reasons, and may obscure the underlying reason, depending.
(Don't worry about it if there's no reason to re-spin, though, I think
it's an extremely minor point. My RB is with or without the change.)
--js
Off-topic: Do you know how we go about enabling the version drop-down on
the RTD site so we can refer back to older documents?
© 2016 - 2024 Red Hat, Inc.