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/
It provides, IMHO, a nice improvement on themes selection. This series
is a v2 of the other theme-related patches I sent today.
-
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 CSS=my_css.css 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 (THEME);
patch 2 adds a css selection variable (CSS);
patch 3 sets the classic theme to look a little better;
patch 4 adds support for the RTD dark mode theme.
It should be noticed that the RTD dark mode currently has some issues,
as it is actually an override on the top of the original RTD theme.
I suspect it needs to be updated to properly support Sphinx 4.3.0 and
RTD 1.0.0 theme. Yet, it seems useful, as one can always switch to daylight
mode in runtime, if something looks odd with it enabled.
Mauro Carvalho Chehab (4):
docs: allow selecting a Sphinx theme
docs: allow to pass extra CSS themes via make
docs: set format for the classic mode
docs: add support for RTD dark mode
Documentation/Makefile | 9 +-
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, 138 insertions(+), 37 deletions(-)
create mode 100644 Documentation/sphinx-static/theme_rtd_colors.css
--
2.33.1
This is actually an overlay on the top of the RTD theme, which
requires to include first the RTD theme.
While the CSS overlay file for RTD can be used here, the color
settings can't be applied, as they would do weird things. So,
we need to split the color-dependent logic in order to place it
into a separate file.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
See [PATCH v2 0/4] at: https://lore.kernel.org/all/[email protected]/
Documentation/conf.py | 15 +++++++-
.../sphinx-static/theme_overrides.css | 16 +-------
.../sphinx-static/theme_rtd_colors.css | 37 +++++++++++++++++++
3 files changed, 53 insertions(+), 15 deletions(-)
create mode 100644 Documentation/sphinx-static/theme_rtd_colors.css
diff --git a/Documentation/conf.py b/Documentation/conf.py
index d1b6f602b34d..6f4b35bccf3a 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -215,7 +215,7 @@ html_css_files = []
if "THEME" in os.environ:
html_theme = os.environ["THEME"]
-if html_theme == 'sphinx_rtd_theme':
+if html_theme == 'sphinx_rtd_theme' or html_theme == 'sphinx_rtd_dark_mode':
# Read the Docs theme
try:
import sphinx_rtd_theme
@@ -227,6 +227,19 @@ if html_theme == 'sphinx_rtd_theme':
html_css_files = [
'theme_overrides.css',
]
+
+ # Read the Docs dark mode override theme
+ if html_theme == 'sphinx_rtd_dark_mode':
+ try:
+ import sphinx_rtd_dark_mode
+ extensions.append('sphinx_rtd_dark_mode')
+ except ImportError:
+ html_theme == 'sphinx_rtd_theme'
+
+ if html_theme == 'sphinx_rtd_theme':
+ # Add color-specific RTD normal mode
+ html_css_files.append('theme_rtd_colors.css')
+
except ImportError:
html_theme = 'classic'
diff --git a/Documentation/sphinx-static/theme_overrides.css b/Documentation/sphinx-static/theme_overrides.css
index 459ec5b29d68..f6f2b941a5d6 100644
--- a/Documentation/sphinx-static/theme_overrides.css
+++ b/Documentation/sphinx-static/theme_overrides.css
@@ -1,14 +1,14 @@
/* -*- coding: utf-8; mode: css -*-
*
* Sphinx HTML theme customization: read the doc
- *
+ * Please don't add any color definition here, as the theme should
+ * work for both normal and dark modes.
*/
/* Improve contrast and increase size for easier reading. */
body {
font-family: serif;
- color: black;
font-size: 100%;
}
@@ -16,17 +16,8 @@ h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend {
font-family: sans-serif;
}
-.wy-menu-vertical li.current a {
- color: #505050;
-}
-
-.wy-menu-vertical li.on a, .wy-menu-vertical li.current > a {
- color: #303030;
-}
-
div[class^="highlight"] pre {
font-family: monospace;
- color: black;
font-size: 100%;
}
@@ -104,13 +95,10 @@ div[class^="highlight"] pre {
/* 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
}
diff --git a/Documentation/sphinx-static/theme_rtd_colors.css b/Documentation/sphinx-static/theme_rtd_colors.css
new file mode 100644
index 000000000000..55b6e1c3664b
--- /dev/null
+++ b/Documentation/sphinx-static/theme_rtd_colors.css
@@ -0,0 +1,37 @@
+/* -*- coding: utf-8; mode: css -*-
+ *
+ * Sphinx HTML theme customization: color settings for RTD (non-dark) theme
+ *
+ */
+
+/* Improve contrast and increase size for easier reading. */
+
+body {
+ color: black;
+}
+
+.wy-menu-vertical li.current a {
+ color: #505050;
+}
+
+.wy-menu-vertical li.on a, .wy-menu-vertical li.current > a {
+ color: #303030;
+}
+
+div[class^="highlight"] pre {
+ color: black;
+}
+
+@media screen {
+
+ /* Menu selection and keystrokes */
+
+ span.menuselection {
+ color: blue;
+ }
+
+ code.kbd, code.kbd span {
+ color: white;
+ background-color: darkblue;
+ }
+}
--
2.33.1