sphinx: adopt kernel readthedoc theme
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> Message-Id: <20210323115328.4146052-1-marcandre.lureau@redhat.com> Reviewed-by: John Snow <jsnow@redhat.com>
This commit is contained in:
Marc-André Lureau
parent
2d3fc4e2b0
commit
73e6aec652
5
docs/_templates/editpage.html
vendored
5
docs/_templates/editpage.html
vendored
|
|
@ -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>
|
||||
52
docs/conf.py
52
docs/conf.py
|
|
@ -29,6 +29,7 @@
|
|||
import os
|
||||
import sys
|
||||
import sphinx
|
||||
from distutils.version import LooseVersion
|
||||
from sphinx.errors import ConfigError
|
||||
|
||||
# Make Sphinx fail cleanly if using an old Python, rather than obscurely
|
||||
|
|
@ -150,38 +151,47 @@ with open(os.path.join(qemu_docdir, 'defs.rst.inc')) as f:
|
|||
# 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 LooseVersion(sphinx_rtd_theme.__version__) >= LooseVersion("0.4.3"):
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
161
docs/sphinx-static/theme_overrides.css
Normal file
161
docs/sphinx-static/theme_overrides.css
Normal file
|
|
@ -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;
|
||||
}
|
||||
}
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -39,6 +39,7 @@ ENV PACKAGES \
|
|||
pulseaudio-dev \
|
||||
python3 \
|
||||
py3-sphinx \
|
||||
py3-sphinx_rtd_theme \
|
||||
shadow \
|
||||
snappy-dev \
|
||||
spice-dev \
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -92,6 +92,7 @@ ENV PACKAGES \
|
|||
python3-pillow \
|
||||
python3-pip \
|
||||
python3-sphinx \
|
||||
python3-sphinx_rtd_theme \
|
||||
python3-virtualenv \
|
||||
rdma-core-devel \
|
||||
SDL2-devel \
|
||||
|
|
|
|||
|
|
@ -63,6 +63,7 @@ ENV PACKAGES \
|
|||
ninja-build \
|
||||
python3-yaml \
|
||||
python3-sphinx \
|
||||
python3-sphinx-rtd-theme \
|
||||
sparse \
|
||||
xfslibs-dev
|
||||
RUN apt-get update && \
|
||||
|
|
|
|||
|
|
@ -48,6 +48,7 @@ ENV PACKAGES \
|
|||
make \
|
||||
python3-yaml \
|
||||
python3-sphinx \
|
||||
python3-sphinx-rtd-theme \
|
||||
ninja-build \
|
||||
sparse \
|
||||
xfslibs-dev
|
||||
|
|
|
|||
|
|
@ -58,6 +58,7 @@ ENV PACKAGES flex bison \
|
|||
python3-pil \
|
||||
python3-pip \
|
||||
python3-sphinx \
|
||||
python3-sphinx-rtd-theme \
|
||||
python3-venv \
|
||||
python3-yaml \
|
||||
rpm2cpio \
|
||||
|
|
|
|||
Loading…
Reference in a new issue