Hi On Mon, Mar 22, 2021 at 2:52 PM <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 Sorry, this link is outdated now. Here is a more stable one: https://elmarco.fedorapeople.org/Screenshot_2021-03-22%20Welcome%20to%20QEMU%e2%80%99s%20documentation%20%e2%80%94%20QEMU%20documentation.png > > Signed-off-by: Marc-André Lureau <marcandre.lur...@redhat.com> > Tested-by: Bin Meng <bmeng...@gmail.com> > --- > v4: > - resend (with Bin T-b, and with minor style fixes) > > docs/_templates/editpage.html | 5 - > docs/conf.py | 50 ++++--- > 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, 196 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..17e0319d69 100644 > --- a/docs/conf.py > +++ b/docs/conf.py > @@ -151,37 +151,47 @@ > # 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", > + } > + > +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/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 > >
