All of lore.kernel.org
 help / color / mirror / Atom feed
* [PATCH v3 0/4] docs: add better support for Sphinx themes and CSS
@ 2021-12-01 17:59 Mauro Carvalho Chehab
  2021-12-01 17:59 ` [PATCH v3 1/4] docs: allow selecting a Sphinx theme Mauro Carvalho Chehab
                   ` (3 more replies)
  0 siblings, 4 replies; 14+ messages in thread
From: Mauro Carvalho Chehab @ 2021-12-01 17:59 UTC (permalink / raw)
  To: Linux Doc Mailing List, Jonathan Corbet
  Cc: Mauro Carvalho Chehab, linux-kernel, Jani Nikula, Randy Dunlap,
	Akira Yokosawa, Nícolas F. R. A. Prado, Alex Shi,
	Andrew Klychkov, Miguel Ojeda

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.

---

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 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



^ permalink raw reply	[flat|nested] 14+ messages in thread

* [PATCH v3 1/4] docs: allow selecting a Sphinx theme
  2021-12-01 17:59 [PATCH v3 0/4] docs: add better support for Sphinx themes and CSS Mauro Carvalho Chehab
@ 2021-12-01 17:59 ` Mauro Carvalho Chehab
  2021-12-02 11:24   ` Miguel Ojeda
  2021-12-06 19:12   ` Jonathan Corbet
  2021-12-01 17:59 ` [PATCH v3 2/4] docs: allow to pass extra CSS themes via make Mauro Carvalho Chehab
                   ` (2 subsequent siblings)
  3 siblings, 2 replies; 14+ messages in thread
From: Mauro Carvalho Chehab @ 2021-12-01 17:59 UTC (permalink / raw)
  To: Linux Doc Mailing List, Jonathan Corbet
  Cc: Mauro Carvalho Chehab, Akira Yokosawa, Jani Nikula,
	Nícolas F. R. A. Prado, Randy Dunlap, Andrew Klychkov,
	Miguel Ojeda, linux-kernel

Instead of having RTD as an almost mandatory theme, allow the
user to select other themes via a THEMES environment var.

There's a catch, though: as the current theme override logic is
dependent of the RTD theme, we need to move the code which
adds the CSS overrides to be inside the RTD theme logic.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---

See [PATCH v3 0/4] at: https://lore.kernel.org/all/cover.1638369365.git.mchehab+huawei@kernel.org/

 Documentation/Makefile             |  3 ++
 Documentation/conf.py              | 52 +++++++++++++++++-------------
 Documentation/doc-guide/sphinx.rst |  8 +++++
 3 files changed, 41 insertions(+), 22 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index c3feb657b654..d4039d77b32a 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -19,6 +19,7 @@ endif
 SPHINXBUILD   = sphinx-build
 SPHINXOPTS    =
 SPHINXDIRS    = .
+THEME         =
 _SPHINXDIRS   = $(sort $(patsubst $(srctree)/Documentation/%/index.rst,%,$(wildcard $(srctree)/Documentation/*/index.rst)))
 SPHINX_CONF   = conf.py
 PAPER         =
@@ -154,4 +155,6 @@ dochelp:
 	@echo  '  make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build'
 	@echo  '  configuration. This is e.g. useful to build with nit-picking config.'
 	@echo
+	@echo '   make THEME={sphinx-theme} selects a different Sphinx theme.'
+	@echo
 	@echo  '  Default location for the generated documents is Documentation/output'
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 76e5eb5cb62b..082c3ac9dd33 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -208,16 +208,36 @@ highlight_language = 'none'
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 
-# The Read the Docs theme is available from
-# - https://github.com/snide/sphinx_rtd_theme
-# - https://pypi.python.org/pypi/sphinx_rtd_theme
-# - python-sphinx-rtd-theme package (on Debian)
-try:
-    import sphinx_rtd_theme
-    html_theme = 'sphinx_rtd_theme'
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-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')
+# Default theme
+html_theme = 'sphinx_rtd_theme'
+
+if "THEME" in os.environ:
+    html_theme = os.environ["THEME"]
+
+if html_theme == 'sphinx_rtd_theme':
+    # Read the Docs theme
+    try:
+        import sphinx_rtd_theme
+        html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+        # 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".
+        html_css_files = [
+            'theme_overrides.css',
+        ]
+    except ImportError:
+        html_theme = 'classic'
+
+if major <= 1 and minor < 8:
+    html_context = {
+        'css_files': [],
+    }
+
+    for l in html_css_files:
+        html_context['css_files'].append('_static/' + l)
+
+sys.stderr.write("Using %s theme\n" % html_theme)
 
 # 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
@@ -246,20 +266,8 @@ except ImportError:
 # 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".
-
 html_static_path = ['sphinx-static']
 
-html_css_files = [
-    'theme_overrides.css',
-]
-
-if major <= 1 and minor < 8:
-    html_context = {
-        'css_files': [
-            '_static/theme_overrides.css',
-        ],
-    }
-
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.
diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index e445cb146efe..33a527f5ae64 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -138,6 +138,14 @@ To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make
 variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose
 output.
 
+By default, the build will try to use the Read the Docs sphinx theme:
+
+    https://github.com/readthedocs/sphinx_rtd_theme
+
+If the theme is not available, it will fall-back to the classic one.
+
+The Sphinx theme can be overriden by using the ``THEME`` make variable.
+
 To remove the generated documentation, run ``make cleandocs``.
 
 Writing Documentation
-- 
2.33.1


^ permalink raw reply related	[flat|nested] 14+ messages in thread

* [PATCH v3 2/4] docs: allow to pass extra CSS themes via make
  2021-12-01 17:59 [PATCH v3 0/4] docs: add better support for Sphinx themes and CSS Mauro Carvalho Chehab
  2021-12-01 17:59 ` [PATCH v3 1/4] docs: allow selecting a Sphinx theme Mauro Carvalho Chehab
@ 2021-12-01 17:59 ` Mauro Carvalho Chehab
  2021-12-01 17:59 ` [PATCH v3 3/4] docs: set format for the classic mode Mauro Carvalho Chehab
  2021-12-01 17:59 ` [PATCH v3 4/4] docs: add support for RTD dark mode Mauro Carvalho Chehab
  3 siblings, 0 replies; 14+ messages in thread
From: Mauro Carvalho Chehab @ 2021-12-01 17:59 UTC (permalink / raw)
  To: Linux Doc Mailing List, Jonathan Corbet
  Cc: Mauro Carvalho Chehab, Akira Yokosawa, Jani Nikula,
	Nícolas F. R. A. Prado, Randy Dunlap, Alex Shi,
	Andrew Klychkov, linux-kernel

Specially when the RTD theme is not used, it makes sense to
allow specifying extra CSS files via a make variable.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---

See [PATCH v3 0/4] at: https://lore.kernel.org/all/cover.1638369365.git.mchehab+huawei@kernel.org/

 Documentation/Makefile             | 8 +++++++-
 Documentation/conf.py              | 7 +++++++
 Documentation/doc-guide/sphinx.rst | 3 +++
 3 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index d4039d77b32a..b3ccd1925cd3 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -20,6 +20,7 @@ SPHINXBUILD   = sphinx-build
 SPHINXOPTS    =
 SPHINXDIRS    = .
 THEME         =
+CSS           =
 _SPHINXDIRS   = $(sort $(patsubst $(srctree)/Documentation/%/index.rst,%,$(wildcard $(srctree)/Documentation/*/index.rst)))
 SPHINX_CONF   = conf.py
 PAPER         =
@@ -85,7 +86,10 @@ quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
 	-D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \
 	$(ALLSPHINXOPTS) \
 	$(abspath $(srctree)/$(src)/$5) \
-	$(abspath $(BUILDDIR)/$3/$4)
+	$(abspath $(BUILDDIR)/$3/$4) && \
+	if [ "x$(CSS)" != "x" ]; then \
+		cp $(CSS) $(BUILDDIR)/$3/_static/; \
+	fi
 
 htmldocs:
 	@$(srctree)/scripts/sphinx-pre-install --version-check
@@ -157,4 +161,6 @@ dochelp:
 	@echo
 	@echo '   make THEME={sphinx-theme} selects a different Sphinx theme.'
 	@echo
+	@echo '   make CSS={a .css file} adds a CSS override file for html/epub output.'
+	@echo
 	@echo  '  Default location for the generated documents is Documentation/output'
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 082c3ac9dd33..0e2593e4d357 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -210,6 +210,7 @@ highlight_language = 'none'
 
 # Default theme
 html_theme = 'sphinx_rtd_theme'
+html_css_files = []
 
 if "THEME" in os.environ:
     html_theme = os.environ["THEME"]
@@ -229,6 +230,12 @@ if html_theme == 'sphinx_rtd_theme':
     except ImportError:
         html_theme = 'classic'
 
+if "CSS" in os.environ:
+    css = os.environ["CSS"].split(" ")
+
+    for l in css:
+        html_css_files.append(l)
+
 if major <= 1 and minor < 8:
     html_context = {
         'css_files': [],
diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index 33a527f5ae64..e25bc033aad3 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -138,6 +138,9 @@ To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make
 variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose
 output.
 
+It is also possible to pass an extra CSS overlay file, in order to customize
+the html layout, by using the ``CSS`` make variable.
+
 By default, the build will try to use the Read the Docs sphinx theme:
 
     https://github.com/readthedocs/sphinx_rtd_theme
-- 
2.33.1


^ permalink raw reply related	[flat|nested] 14+ messages in thread

* [PATCH v3 3/4] docs: set format for the classic mode
  2021-12-01 17:59 [PATCH v3 0/4] docs: add better support for Sphinx themes and CSS Mauro Carvalho Chehab
  2021-12-01 17:59 ` [PATCH v3 1/4] docs: allow selecting a Sphinx theme Mauro Carvalho Chehab
  2021-12-01 17:59 ` [PATCH v3 2/4] docs: allow to pass extra CSS themes via make Mauro Carvalho Chehab
@ 2021-12-01 17:59 ` Mauro Carvalho Chehab
  2021-12-01 17:59 ` [PATCH v3 4/4] docs: add support for RTD dark mode Mauro Carvalho Chehab
  3 siblings, 0 replies; 14+ messages in thread
From: Mauro Carvalho Chehab @ 2021-12-01 17:59 UTC (permalink / raw)
  To: Linux Doc Mailing List, Jonathan Corbet
  Cc: Mauro Carvalho Chehab, Akira Yokosawa, Jani Nikula, Randy Dunlap,
	linux-kernel

When RTD is not installed or when THEME=classic is used, the
produced docs contain some weird selections. As this theme has
several variables to customize it, set them, in order to produce
a nicer output.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---

See [PATCH v3 0/4] at: https://lore.kernel.org/all/cover.1638369365.git.mchehab+huawei@kernel.org/

 Documentation/conf.py | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 0e2593e4d357..d1b6f602b34d 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -244,6 +244,36 @@ if major <= 1 and minor < 8:
     for l in html_css_files:
         html_context['css_files'].append('_static/' + l)
 
+if  html_theme == 'classic':
+    html_theme_options = {
+        'rightsidebar':        False,
+        'stickysidebar':       True,
+        'collapsiblesidebar':  True,
+        'externalrefs':        False,
+
+        'footerbgcolor':       "white",
+        'footertextcolor':     "white",
+        'sidebarbgcolor':      "white",
+        'sidebarbtncolor':     "black",
+        'sidebartextcolor':    "black",
+        'sidebarlinkcolor':    "#686bff",
+        'relbarbgcolor':       "#133f52",
+        'relbartextcolor':     "white",
+        'relbarlinkcolor':     "white",
+        'bgcolor':             "white",
+        'textcolor':           "black",
+        'headbgcolor':         "#f2f2f2",
+        'headtextcolor':       "#20435c",
+        'headlinkcolor':       "#c60f0f",
+        'linkcolor':           "#355f7c",
+        'visitedlinkcolor':    "#355f7c",
+        'codebgcolor':         "#3f3f3f",
+        'codetextcolor':       "white",
+
+        'bodyfont':            "serif",
+        'headfont':            "sans-serif",
+    }
+
 sys.stderr.write("Using %s theme\n" % html_theme)
 
 # Theme options are theme-specific and customize the look and feel of a theme
-- 
2.33.1


^ permalink raw reply related	[flat|nested] 14+ messages in thread

* [PATCH v3 4/4] docs: add support for RTD dark mode
  2021-12-01 17:59 [PATCH v3 0/4] docs: add better support for Sphinx themes and CSS Mauro Carvalho Chehab
                   ` (2 preceding siblings ...)
  2021-12-01 17:59 ` [PATCH v3 3/4] docs: set format for the classic mode Mauro Carvalho Chehab
@ 2021-12-01 17:59 ` Mauro Carvalho Chehab
  3 siblings, 0 replies; 14+ messages in thread
From: Mauro Carvalho Chehab @ 2021-12-01 17:59 UTC (permalink / raw)
  To: Linux Doc Mailing List, Jonathan Corbet
  Cc: Mauro Carvalho Chehab, Akira Yokosawa, Jani Nikula, Randy Dunlap,
	linux-kernel

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 <mchehab+huawei@kernel.org>
---

See [PATCH v3 0/4] at: https://lore.kernel.org/all/cover.1638369365.git.mchehab+huawei@kernel.org/

 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


^ permalink raw reply related	[flat|nested] 14+ messages in thread

* Re: [PATCH v3 1/4] docs: allow selecting a Sphinx theme
  2021-12-01 17:59 ` [PATCH v3 1/4] docs: allow selecting a Sphinx theme Mauro Carvalho Chehab
@ 2021-12-02 11:24   ` Miguel Ojeda
  2021-12-02 11:47     ` Mauro Carvalho Chehab
  2021-12-06 19:12   ` Jonathan Corbet
  1 sibling, 1 reply; 14+ messages in thread
From: Miguel Ojeda @ 2021-12-02 11:24 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Linux Doc Mailing List, Jonathan Corbet, Akira Yokosawa,
	Jani Nikula, Nícolas F. R. A. Prado, Randy Dunlap,
	Andrew Klychkov, Miguel Ojeda, linux-kernel

On Wed, Dec 1, 2021 at 6:59 PM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> Instead of having RTD as an almost mandatory theme, allow the
> user to select other themes via a THEMES environment var.
>
> There's a catch, though: as the current theme override logic is
> dependent of the RTD theme, we need to move the code which
> adds the CSS overrides to be inside the RTD theme logic.

Does Sphinx support leaving the selection of the theme to "runtime",
i.e. to let users pick a theme from a few from a combobox (e.g.
light/dark)?

I assume not, but asking just in case.

Cheers,
Miguel

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [PATCH v3 1/4] docs: allow selecting a Sphinx theme
  2021-12-02 11:24   ` Miguel Ojeda
@ 2021-12-02 11:47     ` Mauro Carvalho Chehab
  2021-12-02 11:50       ` Miguel Ojeda
  2021-12-03 14:08       ` Mauro Carvalho Chehab
  0 siblings, 2 replies; 14+ messages in thread
From: Mauro Carvalho Chehab @ 2021-12-02 11:47 UTC (permalink / raw)
  To: Miguel Ojeda
  Cc: Linux Doc Mailing List, Jonathan Corbet, Akira Yokosawa,
	Jani Nikula, Nícolas F. R. A. Prado, Randy Dunlap,
	Andrew Klychkov, Miguel Ojeda, linux-kernel

Em Thu, 2 Dec 2021 12:24:53 +0100
Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> escreveu:

> On Wed, Dec 1, 2021 at 6:59 PM Mauro Carvalho Chehab
> <mchehab+huawei@kernel.org> wrote:
> >
> > Instead of having RTD as an almost mandatory theme, allow the
> > user to select other themes via a THEMES environment var.
> >
> > There's a catch, though: as the current theme override logic is
> > dependent of the RTD theme, we need to move the code which
> > adds the CSS overrides to be inside the RTD theme logic.  
> 
> Does Sphinx support leaving the selection of the theme to "runtime",
> i.e. to let users pick a theme from a few from a combobox (e.g.
> light/dark)?
> 
> I assume not, but asking just in case.

The RTD dark theme allows that. It basically places a <sun>/<moon>
icon. When such icon is clicked, it switches between light/dark.

Thanks,
Mauro

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [PATCH v3 1/4] docs: allow selecting a Sphinx theme
  2021-12-02 11:47     ` Mauro Carvalho Chehab
@ 2021-12-02 11:50       ` Miguel Ojeda
  2021-12-03 14:08       ` Mauro Carvalho Chehab
  1 sibling, 0 replies; 14+ messages in thread
From: Miguel Ojeda @ 2021-12-02 11:50 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Linux Doc Mailing List, Jonathan Corbet, Akira Yokosawa,
	Jani Nikula, Nícolas F. R. A. Prado, Randy Dunlap,
	Andrew Klychkov, Miguel Ojeda, linux-kernel

On Thu, Dec 2, 2021 at 12:47 PM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> The RTD dark theme allows that. It basically places a <sun>/<moon>
> icon. When such icon is clicked, it switches between light/dark.

Ah, that is great! Thanks!

Cheers,
Miguel

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [PATCH v3 1/4] docs: allow selecting a Sphinx theme
  2021-12-02 11:47     ` Mauro Carvalho Chehab
  2021-12-02 11:50       ` Miguel Ojeda
@ 2021-12-03 14:08       ` Mauro Carvalho Chehab
  1 sibling, 0 replies; 14+ messages in thread
From: Mauro Carvalho Chehab @ 2021-12-03 14:08 UTC (permalink / raw)
  To: Miguel Ojeda
  Cc: Linux Doc Mailing List, Jonathan Corbet, Akira Yokosawa,
	Jani Nikula, Nícolas F. R. A. Prado, Randy Dunlap,
	Andrew Klychkov, Miguel Ojeda, linux-kernel, linux-media

Em Thu, 2 Dec 2021 12:47:00 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu:

> Em Thu, 2 Dec 2021 12:24:53 +0100
> Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> escreveu:
> 
> > On Wed, Dec 1, 2021 at 6:59 PM Mauro Carvalho Chehab
> > <mchehab+huawei@kernel.org> wrote:  
> > >
> > > Instead of having RTD as an almost mandatory theme, allow the
> > > user to select other themes via a THEMES environment var.
> > >
> > > There's a catch, though: as the current theme override logic is
> > > dependent of the RTD theme, we need to move the code which
> > > adds the CSS overrides to be inside the RTD theme logic.    
> > 
> > Does Sphinx support leaving the selection of the theme to "runtime",
> > i.e. to let users pick a theme from a few from a combobox (e.g.
> > light/dark)?
> > 
> > I assume not, but asking just in case.  
> 
> The RTD dark theme allows that. It basically places a <sun>/<moon>
> icon. When such icon is clicked, it switches between light/dark.

Btw, I'm now using it at:

	https://linuxtv.org/downloads/v4l-dvb-apis-new/index.html

As we use a dark theme at linuxtv.org since ever.

It was built with the following script:

	CSS=linuxtv.css
	THEME=sphinx_rtd_dark_mode

	cat << EOF > $CSS
	  html body {
	    font-family: arial,helvetica,sans-serif;
	    margin: 0px;
	    padding: 0px;
	  }
	  html[data-theme='dark'] body {
	    color: white !important;
	  }
	  html[data-theme='dark'] .sig-name {
	    color: green !important;
	  }
	  html[data-theme='dark'] .wy-menu-vertical a {
	    color: #ffcc00 !important;
	  }
	  html[data-theme="dark"] h1, html[data-theme="dark"] h2, html[data-theme="dark"] h3 {
	    color: #ffcc00 !important;
	  }
	  html[data-theme="dark"] h4, html[data-theme="dark"] h5, html[data-theme="dark"] h6 {
	    color: #ffcc00 !important;
	  }
	  html[data-theme="dark"] h7, html[data-theme="dark"] h8, html[data-theme="dark"] h9 {
	    color: #ffcc00 !important;
	  }
	  html[data-theme="dark"] .wy-nav-content a, html[data-theme="dark"] .wy-nav-content a:visited {
	    color: #ffcc00 !important;
	  }
	EOF

	make SPHINXDIRS='media' CSS='$CSS' THEME='$THEME' htmldocs

Thanks,
Mauro

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [PATCH v3 1/4] docs: allow selecting a Sphinx theme
  2021-12-01 17:59 ` [PATCH v3 1/4] docs: allow selecting a Sphinx theme Mauro Carvalho Chehab
  2021-12-02 11:24   ` Miguel Ojeda
@ 2021-12-06 19:12   ` Jonathan Corbet
  2021-12-06 20:14     ` Mauro Carvalho Chehab
  1 sibling, 1 reply; 14+ messages in thread
From: Jonathan Corbet @ 2021-12-06 19:12 UTC (permalink / raw)
  To: Mauro Carvalho Chehab, Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Akira Yokosawa, Jani Nikula,
	Nícolas F. R. A. Prado, Randy Dunlap, Andrew Klychkov,
	Miguel Ojeda, linux-kernel

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

> Instead of having RTD as an almost mandatory theme, allow the
> user to select other themes via a THEMES environment var.
>
> There's a catch, though: as the current theme override logic is
> dependent of the RTD theme, we need to move the code which
> adds the CSS overrides to be inside the RTD theme logic.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>
> See [PATCH v3 0/4] at: https://lore.kernel.org/all/cover.1638369365.git.mchehab+huawei@kernel.org/
>
>  Documentation/Makefile             |  3 ++
>  Documentation/conf.py              | 52 +++++++++++++++++-------------
>  Documentation/doc-guide/sphinx.rst |  8 +++++
>  3 files changed, 41 insertions(+), 22 deletions(-)

So I'm playing with this now, and definitely want to apply it.  I do
have one little worry, though...  THEME seems like an overly general
name to use here, and seems relatively likely to conflict with other
uses.  THEME= on the command line is fine, but what do you think about
something like DOCS_THEME for the environment variable?  Or even
HTML_THEME as Sphinx uses?

Thanks,

jon

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [PATCH v3 1/4] docs: allow selecting a Sphinx theme
  2021-12-06 19:12   ` Jonathan Corbet
@ 2021-12-06 20:14     ` Mauro Carvalho Chehab
  2021-12-06 22:55       ` Jonathan Corbet
  0 siblings, 1 reply; 14+ messages in thread
From: Mauro Carvalho Chehab @ 2021-12-06 20:14 UTC (permalink / raw)
  To: Jonathan Corbet
  Cc: Linux Doc Mailing List, Akira Yokosawa, Jani Nikula,
	 Nícolas F. R. A. Prado, Randy Dunlap, Andrew Klychkov,
	Miguel Ojeda, linux-kernel

Em Mon, 06 Dec 2021 12:12:12 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > Instead of having RTD as an almost mandatory theme, allow the
> > user to select other themes via a THEMES environment var.
> >
> > There's a catch, though: as the current theme override logic is
> > dependent of the RTD theme, we need to move the code which
> > adds the CSS overrides to be inside the RTD theme logic.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >
> > See [PATCH v3 0/4] at: https://lore.kernel.org/all/cover.1638369365.git.mchehab+huawei@kernel.org/
> >
> >  Documentation/Makefile             |  3 ++
> >  Documentation/conf.py              | 52 +++++++++++++++++-------------
> >  Documentation/doc-guide/sphinx.rst |  8 +++++
> >  3 files changed, 41 insertions(+), 22 deletions(-)  
> 
> So I'm playing with this now, and definitely want to apply it.  I do
> have one little worry, though...  THEME seems like an overly general
> name to use here, and seems relatively likely to conflict with other
> uses.  THEME= on the command line is fine, but what do you think about
> something like DOCS_THEME for the environment variable?  Or even
> HTML_THEME as Sphinx uses?

I'm not sure if we will ever consider a "THEME" environment var for anything
but docs and html stuff. That's why I ended taking the shortest name (for
both THEME and CSS make vars).

Yet, I'm OK if to use whatever name you think it would work best.

Btw, while I didn't actually test, maybe those would also apply to epub,
so, just in case, I guess DOCS_THEME would be preferable, IMO.

Thanks,
Mauro

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [PATCH v3 1/4] docs: allow selecting a Sphinx theme
  2021-12-06 20:14     ` Mauro Carvalho Chehab
@ 2021-12-06 22:55       ` Jonathan Corbet
  2021-12-07  9:16         ` Mauro Carvalho Chehab
  0 siblings, 1 reply; 14+ messages in thread
From: Jonathan Corbet @ 2021-12-06 22:55 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Linux Doc Mailing List, Akira Yokosawa, Jani Nikula,
	Nícolas F. R. A. Prado, Randy Dunlap, Andrew Klychkov,
	Miguel Ojeda, linux-kernel

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

> Em Mon, 06 Dec 2021 12:12:12 -0700
> Jonathan Corbet <corbet@lwn.net> escreveu:
>
>> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
>> 
>> > Instead of having RTD as an almost mandatory theme, allow the
>> > user to select other themes via a THEMES environment var.
>> >
>> > There's a catch, though: as the current theme override logic is
>> > dependent of the RTD theme, we need to move the code which
>> > adds the CSS overrides to be inside the RTD theme logic.
>> >
>> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>> > ---
>> >
>> > See [PATCH v3 0/4] at: https://lore.kernel.org/all/cover.1638369365.git.mchehab+huawei@kernel.org/
>> >
>> >  Documentation/Makefile             |  3 ++
>> >  Documentation/conf.py              | 52 +++++++++++++++++-------------
>> >  Documentation/doc-guide/sphinx.rst |  8 +++++
>> >  3 files changed, 41 insertions(+), 22 deletions(-)  
>> 
>> So I'm playing with this now, and definitely want to apply it.  I do
>> have one little worry, though...  THEME seems like an overly general
>> name to use here, and seems relatively likely to conflict with other
>> uses.  THEME= on the command line is fine, but what do you think about
>> something like DOCS_THEME for the environment variable?  Or even
>> HTML_THEME as Sphinx uses?
>
> I'm not sure if we will ever consider a "THEME" environment var for anything
> but docs and html stuff. That's why I ended taking the shortest name (for
> both THEME and CSS make vars).
>
> Yet, I'm OK if to use whatever name you think it would work best.

I don't doubt we'll have BPF themes one of these years...:)

Seriously, though, I was thinking about uses beyond building kernels.
If I, say, always want to build with the alabaster theme, and so set
THEME to effect that, will it then mess with my desktop environment or
some such?

A quick search doesn't turn up anything, so probably I'm worrying too
much.  Maybe I should just apply it as-is, and we can change it if a
conflict turns up.

Thanks,

jon

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [PATCH v3 1/4] docs: allow selecting a Sphinx theme
  2021-12-06 22:55       ` Jonathan Corbet
@ 2021-12-07  9:16         ` Mauro Carvalho Chehab
  2021-12-07  9:20           ` Mauro Carvalho Chehab
  0 siblings, 1 reply; 14+ messages in thread
From: Mauro Carvalho Chehab @ 2021-12-07  9:16 UTC (permalink / raw)
  To: Jonathan Corbet
  Cc: Linux Doc Mailing List, Akira Yokosawa, Jani Nikula,
	 Nícolas F. R. A. Prado, Randy Dunlap, Andrew Klychkov,
	Miguel Ojeda, linux-kernel

Em Mon, 06 Dec 2021 15:55:50 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > Em Mon, 06 Dec 2021 12:12:12 -0700
> > Jonathan Corbet <corbet@lwn.net> escreveu:
> >  
> >> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> >>   
> >> > Instead of having RTD as an almost mandatory theme, allow the
> >> > user to select other themes via a THEMES environment var.
> >> >
> >> > There's a catch, though: as the current theme override logic is
> >> > dependent of the RTD theme, we need to move the code which
> >> > adds the CSS overrides to be inside the RTD theme logic.
> >> >
> >> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> >> > ---
> >> >
> >> > See [PATCH v3 0/4] at: https://lore.kernel.org/all/cover.1638369365.git.mchehab+huawei@kernel.org/
> >> >
> >> >  Documentation/Makefile             |  3 ++
> >> >  Documentation/conf.py              | 52 +++++++++++++++++-------------
> >> >  Documentation/doc-guide/sphinx.rst |  8 +++++
> >> >  3 files changed, 41 insertions(+), 22 deletions(-)    
> >> 
> >> So I'm playing with this now, and definitely want to apply it.  I do
> >> have one little worry, though...  THEME seems like an overly general
> >> name to use here, and seems relatively likely to conflict with other
> >> uses.  THEME= on the command line is fine, but what do you think about
> >> something like DOCS_THEME for the environment variable?  Or even
> >> HTML_THEME as Sphinx uses?  
> >
> > I'm not sure if we will ever consider a "THEME" environment var for anything
> > but docs and html stuff. That's why I ended taking the shortest name (for
> > both THEME and CSS make vars).
> >
> > Yet, I'm OK if to use whatever name you think it would work best.  
> 
> I don't doubt we'll have BPF themes one of these years...:)

Heh, true :-D

> Seriously, though, I was thinking about uses beyond building kernels.
> If I, say, always want to build with the alabaster theme, and so set
> THEME to effect that, will it then mess with my desktop environment or
> some such?

Hmm... makes sense, but worse case scenario, if someone uses some other
software that would conflict with whatever vars we use, he/she could
always place the vars inside a script ;-)

Here, I created this small script for testing a dark theme:

	#!/bin/bash
	set -e

	if [ "$VIRTUAL_ENV" == "" ]; then
		. sphinx_4.3.0/bin/activate
	fi
	cat << EOF > my_css.css
		body {background-color: #0f0f0f; }
		div.body { background-color: #1f1f1f; }
		.sig.c   .k, .sig.c   .kt, .sig.cpp .k, .sig.cpp .kt { color: #17ff17; }
	EOF
	make CSS=my_css.css THEME=groundwork htmldocs

That not only creates a simple CSS file, but also enables the virtual 
environment if disabled.

> A quick search doesn't turn up anything, so probably I'm worrying too
> much.  Maybe I should just apply it as-is, and we can change it if a
> conflict turns up.

Works for me. If you prefer instead that I rename them, just let
me know and I'll send a v4. Or, if you prefer, Feel free to just 
do a:
	sed s,THEME,foo_THEME,g -i patch1
	sed s,CSS,bar_CSS,g -i patch2

before applying the series ;-)

Thanks,
Mauro

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [PATCH v3 1/4] docs: allow selecting a Sphinx theme
  2021-12-07  9:16         ` Mauro Carvalho Chehab
@ 2021-12-07  9:20           ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 14+ messages in thread
From: Mauro Carvalho Chehab @ 2021-12-07  9:20 UTC (permalink / raw)
  To: Jonathan Corbet
  Cc: Linux Doc Mailing List, Akira Yokosawa, Jani Nikula,
	 Nícolas F. R. A. Prado, Randy Dunlap, Andrew Klychkov,
	Miguel Ojeda, linux-kernel

Em Tue, 7 Dec 2021 10:16:22 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu:

> Em Mon, 06 Dec 2021 15:55:50 -0700
> Jonathan Corbet <corbet@lwn.net> escreveu:
> 
> > Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> >   
> > > Em Mon, 06 Dec 2021 12:12:12 -0700
> > > Jonathan Corbet <corbet@lwn.net> escreveu:
> > >    
> > >> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> > >>     
> > >> > Instead of having RTD as an almost mandatory theme, allow the
> > >> > user to select other themes via a THEMES environment var.
> > >> >
> > >> > There's a catch, though: as the current theme override logic is
> > >> > dependent of the RTD theme, we need to move the code which
> > >> > adds the CSS overrides to be inside the RTD theme logic.
> > >> >
> > >> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > >> > ---
> > >> >
> > >> > See [PATCH v3 0/4] at: https://lore.kernel.org/all/cover.1638369365.git.mchehab+huawei@kernel.org/
> > >> >
> > >> >  Documentation/Makefile             |  3 ++
> > >> >  Documentation/conf.py              | 52 +++++++++++++++++-------------
> > >> >  Documentation/doc-guide/sphinx.rst |  8 +++++
> > >> >  3 files changed, 41 insertions(+), 22 deletions(-)      
> > >> 
> > >> So I'm playing with this now, and definitely want to apply it.  I do
> > >> have one little worry, though...  THEME seems like an overly general
> > >> name to use here, and seems relatively likely to conflict with other
> > >> uses.  THEME= on the command line is fine, but what do you think about
> > >> something like DOCS_THEME for the environment variable?  Or even
> > >> HTML_THEME as Sphinx uses?    
> > >
> > > I'm not sure if we will ever consider a "THEME" environment var for anything
> > > but docs and html stuff. That's why I ended taking the shortest name (for
> > > both THEME and CSS make vars).
> > >
> > > Yet, I'm OK if to use whatever name you think it would work best.    
> > 
> > I don't doubt we'll have BPF themes one of these years...:)  
> 
> Heh, true :-D
> 
> > Seriously, though, I was thinking about uses beyond building kernels.
> > If I, say, always want to build with the alabaster theme, and so set
> > THEME to effect that, will it then mess with my desktop environment or
> > some such?  
> 
> Hmm... makes sense, but worse case scenario, if someone uses some other
> software that would conflict with whatever vars we use, he/she could
> always place the vars inside a script ;-)
> 
> Here, I created this small script for testing a dark theme:
> 
> 	#!/bin/bash
> 	set -e
> 
> 	if [ "$VIRTUAL_ENV" == "" ]; then
> 		. sphinx_4.3.0/bin/activate
> 	fi
> 	cat << EOF > my_css.css
> 		body {background-color: #0f0f0f; }
> 		div.body { background-color: #1f1f1f; }
> 		.sig.c   .k, .sig.c   .kt, .sig.cpp .k, .sig.cpp .kt { color: #17ff17; }
> 	EOF
> 	make CSS=my_css.css THEME=groundwork htmldocs
> 
> That not only creates a simple CSS file, but also enables the virtual 
> environment if disabled.
> 
> > A quick search doesn't turn up anything, so probably I'm worrying too
> > much.  Maybe I should just apply it as-is, and we can change it if a
> > conflict turns up.  
> 
> Works for me. If you prefer instead that I rename them, just let
> me know and I'll send a v4. Or, if you prefer, Feel free to just 
> do a:
> 	sed s,THEME,foo_THEME,g -i patch1
> 	sed s,CSS,bar_CSS,g -i patch2
> 
> before applying the series ;-)

On a second thought, I'd like to adjust the description of patch 4,
so I'll re-send the series anyway. So, I'll submit v4 with:

 	sed s,THEME,DOCS_THEME,g -i patch1
 	sed s,CSS,DOCS_CSS,g -i patch2

Thanks,
Mauro

^ permalink raw reply	[flat|nested] 14+ messages in thread

end of thread, other threads:[~2021-12-07  9:20 UTC | newest]

Thread overview: 14+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-12-01 17:59 [PATCH v3 0/4] docs: add better support for Sphinx themes and CSS Mauro Carvalho Chehab
2021-12-01 17:59 ` [PATCH v3 1/4] docs: allow selecting a Sphinx theme Mauro Carvalho Chehab
2021-12-02 11:24   ` Miguel Ojeda
2021-12-02 11:47     ` Mauro Carvalho Chehab
2021-12-02 11:50       ` Miguel Ojeda
2021-12-03 14:08       ` Mauro Carvalho Chehab
2021-12-06 19:12   ` Jonathan Corbet
2021-12-06 20:14     ` Mauro Carvalho Chehab
2021-12-06 22:55       ` Jonathan Corbet
2021-12-07  9:16         ` Mauro Carvalho Chehab
2021-12-07  9:20           ` Mauro Carvalho Chehab
2021-12-01 17:59 ` [PATCH v3 2/4] docs: allow to pass extra CSS themes via make Mauro Carvalho Chehab
2021-12-01 17:59 ` [PATCH v3 3/4] docs: set format for the classic mode Mauro Carvalho Chehab
2021-12-01 17:59 ` [PATCH v3 4/4] docs: add support for RTD dark mode Mauro Carvalho Chehab

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.