Re: [PATCH v4] sphinx: adopt kernel readthedoc theme

["Marc-André Lureau" <marcandre.lureau@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 15910 bytes --]

On Mon, Mar 22, 2021 at 2:59 PM Marc-André Lureau <
marcandre.lureau@redhat.com> wrote:

> Hi
>
> On Mon, Mar 22, 2021 at 2:52 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
>
>
> 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
>
>
What about simplifying the various section titles?
https://elmarco.fedorapeople.org/Screenshot_2021-03-22%20Welcome%20to%20QEMU%e2%80%99s%20documentation%20%e2%80%94%20QEMU%20documentation(1).png


>>
>> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
>> Tested-by: Bin Meng <bmeng.cn@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
>>
>>

[-- Attachment #2: Type: text/html, Size: 20520 bytes --]