linux-kernel - [PATCH v4 0/4] docs: add better support for Sphinx themes and CSS

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Date:   Tue,  7 Dec 2021 10:52:58 +0100
From:   Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To:     Jonathan Corbet <corbet@....net>,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>
Cc:     Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
        linux-kernel@...r.kernel.org,
        Jani Nikula <jani.nikula@...ux.intel.com>,
        Randy Dunlap <rdunlap@...radead.org>,
        Akira Yokosawa <akiyks@...il.com>,
        Nícolas F. R. A. Prado 
        <nfraprado@...tonmail.com>, Alex Shi <alexs@...nel.org>
Subject: [PATCH v4 0/4] docs: add better support for Sphinx themes and CSS

Hi Jon,

This series comes after my patch fixing Sphinx support for RTD 1.0.0:
 https://lore.kernel.org/lkml/80009f0d17ea0840d81e7e16fff6e7677919fdfc.1638004294.git.mchehab+huawei@kernel.org/

On this version, I renamed the vars to DOCS_CSS and DOCS_THEME,
based on our previous discussion.

I also changed the description of patch 4, better explaining how to
override the CSS theme and giving an example that looks fine,
at least for my eyes.

-

Sphinx allows using different output templates for HTML (and e-pub).

Right now, the Kernel was hardcoded to use the Read the Docs theme,
falling back to whatever default is setup on a given Sphinx version.

Well, themes and templates are actually an user preference.

This patch set allows selecting different themes and even provide
extra CSS override files.

With that, one could, for instance, do things like:

$ echo "body { color: darkgreen; } div.body { color: darkgreen; } " >my_css.css && make SPHINXDIRS=input DOCS_CSS=my_css.css DOCS_THEME=nature htmldocs

In order to use the Sphinx nature theme with the normal font in green.

patch 1 adds a theme selection make variable (DOCS_THEME);
patch 2 adds a css selection variable (DOCS_CSS);
patch 3 sets the classic theme to look a little better, as this will be
  used if  the RTD theme is not installed;
patch 4 adds support for the RTD dark mode theme, which seems to
  be currently the only theme that allows the user to switch between
  dark/light mode when visualizing the documentation.

---

v4:
  - vars were renamed to DOCS_CSS and DOCS_THEME;
  - improved description of patch 4.
v3:
   - Fixed an issue at the logic which copies the extra CSS files on patch 2.

Mauro Carvalho Chehab (4):
  docs: allow selecting a Sphinx theme
  docs: allow to pass extra DOCS_CSS themes via make
  docs: set format for the classic mode
  docs: add support for RTD dark mode

 Documentation/Makefile                        |  11 +-
 Documentation/conf.py                         | 102 ++++++++++++++----
 Documentation/doc-guide/sphinx.rst            |  11 ++
 .../sphinx-static/theme_overrides.css         |  16 +--
 .../sphinx-static/theme_rtd_colors.css        |  37 +++++++
 5 files changed, 140 insertions(+), 37 deletions(-)
 create mode 100644 Documentation/sphinx-static/theme_rtd_colors.css

-- 
2.33.1