[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH v2] RFC: sphinx: adopt kernel readthedoc theme
|
From: |
Bin Meng |
|
Subject: |
Re: [PATCH v2] RFC: sphinx: adopt kernel readthedoc theme |
|
Date: |
Wed, 20 Jan 2021 16:45:12 +0800 |
On Wed, Jan 20, 2021 at 3:41 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 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 | 43 ++++---
> docs/devel/_templates/editpage.html | 5 -
> docs/interop/_templates/editpage.html | 5 -
> docs/specs/_templates/editpage.html | 5 -
> docs/sphinx-static/theme_overrides.css | 157 +++++++++++++++++++++++++
> docs/system/_templates/editpage.html | 5 -
> docs/tools/_templates/editpage.html | 5 -
> docs/user/_templates/editpage.html | 5 -
> 9 files changed, 181 insertions(+), 54 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..2d9e8148a9 100644
> --- a/docs/conf.py
> +++ b/docs/conf.py
> @@ -150,38 +150,43 @@ 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
> + 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 = {
> + "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",
nits: there is a trailing space here
> + "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/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..6bacf9141e
> --- /dev/null
> +++ b/docs/sphinx-static/theme_overrides.css
> @@ -0,0 +1,157 @@
> +/* -*- 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-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>
> --
When sphinx_rtd_theme is not installed, with this patch no html doc is
generated at all. After installing sphinx_rtd_theme html doc can be
generated again.
Please take a look.
Regards,
Bin