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

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

[Mauro Carvalho Chehab]

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

[PATCH v4 1/4] docs: allow selecting a Sphinx theme

[Mauro Carvalho Chehab]

Instead of having RTD as an almost mandatory theme, allow the
user to select other themes via DOCS_THEME 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 v4 0/4] at: https://lore.kernel.org/all/cover.1638870323.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..11f8b3b9a7ef 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -19,6 +19,7 @@ endif
 SPHINXBUILD   = sphinx-build
 SPHINXOPTS    =
 SPHINXDIRS    = .
+DOCS_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 DOCS_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..9a6a1009c2c4 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 "DOCS_THEME" in os.environ:
+    html_theme = os.environ["DOCS_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..bef276c58ebe 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 ``DOCS_THEME`` make variable.
+
 To remove the generated documentation, run ``make cleandocs``.
 
 Writing Documentation
-- 
2.33.1

[PATCH v4 2/4] docs: allow to pass extra DOCS_CSS themes via make

[Mauro Carvalho Chehab]

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 v4 0/4] at: https://lore.kernel.org/all/cover.1638870323.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 11f8b3b9a7ef..9f0f53db2f10 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -20,6 +20,7 @@ SPHINXBUILD   = sphinx-build
 SPHINXOPTS    =
 SPHINXDIRS    = .
 DOCS_THEME    =
+DOCS_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$(DOCS_CSS)" != "x" ]; then \
+		cp $(DOCS_CSS) $(BUILDDIR)/$3/_static/; \
+	fi
 
 htmldocs:
 	@$(srctree)/scripts/sphinx-pre-install --version-check
@@ -157,4 +161,6 @@ dochelp:
 	@echo
 	@echo '   make DOCS_THEME={sphinx-theme} selects a different Sphinx theme.'
 	@echo
+	@echo '   make DOCS_CSS={a .css file} adds a DOCS_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 9a6a1009c2c4..923496396c3f 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 "DOCS_THEME" in os.environ:
     html_theme = os.environ["DOCS_THEME"]
@@ -229,6 +230,12 @@ if html_theme == 'sphinx_rtd_theme':
     except ImportError:
         html_theme = 'classic'
 
+if "DOCS_CSS" in os.environ:
+    css = os.environ["DOCS_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 bef276c58ebe..7fb6e6168bbb 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 DOCS_CSS overlay file, in order to customize
+the html layout, by using the ``DOCS_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

[PATCH v4 3/4] docs: set format for the classic mode

[Mauro Carvalho Chehab]

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 v4 0/4] at: https://lore.kernel.org/all/cover.1638870323.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 923496396c3f..c8efe82d1404 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

[PATCH v4 4/4] docs: add support for RTD dark mode

[Mauro Carvalho Chehab]

This is actually an overlay on the top of the RTD theme, which
requires to include first the RTD theme.

It should be noticed that, when the dark theme is used, the
DOCS_CSS files won't be the last CSS themes. So, it won't
override the dark.css style by default. So, it is needed
to force the them override with "!important".

This small script, for instance, produces a nice output with
the RTD dark theme:

	DOCS_THEME=sphinx_rtd_dark_mode
	cat << EOF > dark_override.css
	  html body {
	    font-family: arial,helvetica,sans-serif;
	  }
	  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 DOCS_CSS=dark_override.css DOCS_THEME=sphinx_rtd_dark_mode htmldocs

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

See [PATCH v4 0/4] at: https://lore.kernel.org/all/cover.1638870323.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 c8efe82d1404..f07f2e9b9f2c 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -215,7 +215,7 @@ html_css_files = []
 if "DOCS_THEME" in os.environ:
     html_theme = os.environ["DOCS_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

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

[Jonathan Corbet]

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

> 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

I've applied the set, thanks.

jon

Re: [PATCH v4 1/4] docs: allow selecting a Sphinx theme

[Randy Dunlap]

Hi,

On 12/7/21 01:52, Mauro Carvalho Chehab wrote:
> Instead of having RTD as an almost mandatory theme, allow the
> user to select other themes via DOCS_THEME 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 v4 0/4] at: https://lore.kernel.org/all/cover.1638870323.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/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
> index e445cb146efe..bef276c58ebe 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 ``DOCS_THEME`` make variable.

                           overridden

> +
>  To remove the generated documentation, run ``make cleandocs``.
>  
>  Writing Documentation
> 

-- 
~Randy

Re: [PATCH v4 2/4] docs: allow to pass extra DOCS_CSS themes via make

[Randy Dunlap]

Hi--

On 12/7/21 01:53, Mauro Carvalho Chehab wrote:
> 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 v4 0/4] at: https://lore.kernel.org/all/cover.1638870323.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 11f8b3b9a7ef..9f0f53db2f10 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -20,6 +20,7 @@ SPHINXBUILD   = sphinx-build
>  SPHINXOPTS    =
>  SPHINXDIRS    = .
>  DOCS_THEME    =
> +DOCS_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$(DOCS_CSS)" != "x" ]; then \
> +		cp $(DOCS_CSS) $(BUILDDIR)/$3/_static/; \
> +	fi
>  
>  htmldocs:
>  	@$(srctree)/scripts/sphinx-pre-install --version-check
> @@ -157,4 +161,6 @@ dochelp:
>  	@echo
>  	@echo '   make DOCS_THEME={sphinx-theme} selects a different Sphinx theme.'
>  	@echo
> +	@echo '   make DOCS_CSS={a .css file} adds a DOCS_CSS override file for html/epub output.'

The 2 new '   make DOCS_THEME/DOCS_CSS' lines are indented one more space than the
preceding  '  make SPHINX*' lines.

> +	@echo
>  	@echo  '  Default location for the generated documents is Documentation/output'


-- 
~Randy

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

[Randy Dunlap]

Hi Mauro-

On 12/7/21 01:52, Mauro Carvalho Chehab wrote:
> 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

When testing this one, I get:

make DOCS_THEME=nature DOCS_CSS=my_css.css    O=DOCS SPHINXDIRS=x86 -j9 htmldocs
make[1]: Entering directory '/work/lnx/next/next-2021-1210/DOCS'
  SPHINX  htmldocs --> file:///work/lnx/next/next-2021-1210/DOCS/Documentation/output/x86
make[3]: Nothing to be done for 'html'.
Using nature theme
WARNING: Unknown configure key: latex_elements['extrapackages']. ignored.
source directory: x86
cp: cannot stat 'my_css.css': No such file or directory
make[2]: *** [../Documentation/Makefile:96: htmldocs] Error 1
make[1]: *** [/work/lnx/next/next-2021-1210/Makefile:1783: htmldocs] Error 2
make[1]: Leaving directory '/work/lnx/next/next-2021-1210/DOCS'


'my_css.css' is in the top level of the kernel source tree:

$ ls -l  my_css.css
-rw-r--r-- 1 rdunlap users 59 Dec 10 20:16 my_css.css


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


Overall this is looking very good. Thanks for your work on it.

-- 
~Randy