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

qemu-devel
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH v3] sphinx: adopt kernel readthedoc theme

From:	Marc-André Lureau
Subject:	Re: [PATCH v3] sphinx: adopt kernel readthedoc theme
Date:	Sun, 24 Jan 2021 22:19:30 +0400
Hi

On Fri, Jan 22, 2021 at 12:59 AM John Snow <jsnow@redhat.com> wrote:
>
> On 1/20/21 5:25 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 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                               |  47 +++---
> >   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, 193 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..5ee577750b 100644
> > --- a/docs/conf.py
> > +++ b/docs/conf.py
> > @@ -151,37 +151,44 @@ with open(os.path.join(qemu_docdir, 'defs.rst.inc')) 
> > as f:
> >   # 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",
> > +    }
> > +
>
> This needs a default for html_theme_options so that if sphinx_rtd_theme
> isn't present, the build doesn't break when using the fallback to
> alabaster; I'm seeing:
>
> Traceback (most recent call last):
>    File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 361,
> in eval_config_file
>      execfile_(filename, namespace)
>    File "/usr/lib/python3.8/site-packages/sphinx/util/pycompat.py", line
> 81, in execfile_
>      exec(code, _globals)
>    File "/home/jsnow/src/qemu/docs/user/conf.py", line 15, in <module>
>      html_theme_options['description'] = u'User Mode Emulation User''s
> Guide'
> NameError: name 'html_theme_options' is not defined
>

Ok, I don't get that error with sphinx 3.2.1 on fc33...

> etc.
>
> > +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',
> > +]
> > +
>
> We probably don't want this to apply to the alabaster fallback, do we?
>
> (OTOH: It is a fallback, so maybe who cares? Maybe it's not worth the
> complexity to try and support both themes.)

I agree, they seem significantly different to handle, not sure it's
worth the trouble.

>
> > +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
> > +}
> >
>
> Could be a separate patch, MAYBE, explaining that this is to enable the
> "Edit on gitlab!" links, which I do think are very cool and useful.

I am not sure it's worth a different patch, because it is simple
enough and replaces the pre-existing "Page source" link.

>
> >   # 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 = {}
> >
>
> More stuff that damages the alabaster fallback. Putting it back,
> however, causes another problem

arg

>
> >   # 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
>
> If you keep html_sidebars, this fails to build because it's gone now. If
> enough distros have the right theme package, I'm leaning towards just
> chopping out the fallback entirely instead of bothering with the messy
> pain of doing both.

Peter, do you have an opinion about whether we should support a
fallback/default theme?

Given that RTD is the kernel theme, it seems widely available:
https://repology.org/project/python:sphinx-rtd-theme/versions.

I can update the patch to check if the sphinx_rtd_theme module is
present, and error during configure time.

Thanks


>
> --js
>
> > 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 9d42b5a4b8..957ecdcd50 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 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 0b5053f2d0..db249d1506 100644
> > --- a/tests/docker/dockerfiles/fedora.docker
> > +++ b/tests/docker/dockerfiles/fedora.docker
> > @@ -89,6 +89,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 ae889d8482..33c19e1762 100644
> > --- a/tests/docker/dockerfiles/ubuntu2004.docker
> > +++ b/tests/docker/dockerfiles/ubuntu2004.docker
> > @@ -55,6 +55,7 @@ ENV PACKAGES flex bison \
> >       python3-pil \
> >       python3-pip \
> >       python3-sphinx \
> > +    python3-sphinx-rtd-theme \
> >       python3-venv \
> >       python3-yaml \
> >       rpm2cpio \
> >
>
>


-- 
Marc-André Lureau
[Prev in Thread]
Current Thread
[Next in Thread]
[PATCH v3] sphinx: adopt kernel readthedoc theme, marcandre . lureau, 2021/01/20
- Re: [PATCH v3] sphinx: adopt kernel readthedoc theme, no-reply, 2021/01/20
- Re: [PATCH v3] sphinx: adopt kernel readthedoc theme, Bin Meng, 2021/01/20
- Re: [PATCH v3] sphinx: adopt kernel readthedoc theme, John Snow, 2021/01/21
  - Re: [PATCH v3] sphinx: adopt kernel readthedoc theme, Marc-André Lureau <=
    - Re: [PATCH v3] sphinx: adopt kernel readthedoc theme, John Snow, 2021/01/25
    - Re: [PATCH v3] sphinx: adopt kernel readthedoc theme, Marc-André Lureau, 2021/01/25
Prev by Date: Re: [PATCH v2 05/25] hw/sd: sd: Drop sd_crc16()
Next by Date: Re: [PATCH v2 07/25] hw/sd: ssi-sd: Suffix a data block with CRC16
Previous by thread: Re: [PATCH v3] sphinx: adopt kernel readthedoc theme
Next by thread: Re: [PATCH v3] sphinx: adopt kernel readthedoc theme
Index(es):
- Date
- Thread