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
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 <[email protected]>
---
See [PATCH v4 0/4] at: https://lore.kernel.org/all/[email protected]/
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
Mauro Carvalho Chehab <[email protected]> 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
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