docs: add better support for Sphinx themes and CSS

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.

Quoted 7 lines · Mauro Carvalho Chehab

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.

Em Thu, 2 Dec 2021 12:24:53 +0100
Miguel Ojeda <[email protected]> escreveu:

Quoted 10 lines

Quoted 7 lines · Mauro Carvalho Chehab

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.

Quoted 5 lines

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.

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 <[email protected]>

---

See [PATCH v3 0/4] at: https://lore.kernel.org/all/[email protected]/

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

Quoted 8 lines · Mauro Carvalho Chehab

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 <[email protected]>

Quoted 8 lines

---

See [PATCH v3 0/4] at: https://lore.kernel.org/all/[email protected]/

 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?

Em Mon, 06 Dec 2021 12:12:12 -0700
Jonathan Corbet <[email protected]> escreveu:

Quoted 19 lines

Quoted 8 lines · Mauro Carvalho Chehab

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 <[email protected]>

Quoted 8 lines

---

See [PATCH v3 0/4] at: https://lore.kernel.org/all/[email protected]/

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

Quoted 6 lines

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.

Quoted 29 lines · Mauro Carvalho Chehab

Em Mon, 06 Dec 2021 12:12:12 -0700
Jonathan Corbet <[email protected]> escreveu:

Quoted 25 lines

Quoted 8 lines · Mauro Carvalho Chehab

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 <[email protected]>

Quoted 8 lines

---

See [PATCH v3 0/4] at: https://lore.kernel.org/all/[email protected]/

 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?

Quoted 5 lines

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.

Em Mon, 06 Dec 2021 15:55:50 -0700
Jonathan Corbet <[email protected]> escreveu:

Quoted 31 lines

Quoted 29 lines · Mauro Carvalho Chehab

Em Mon, 06 Dec 2021 12:12:12 -0700
Jonathan Corbet <[email protected]> escreveu:

Quoted 25 lines

Quoted 8 lines · Mauro Carvalho Chehab

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 <[email protected]>

Quoted 8 lines

---

See [PATCH v3 0/4] at: https://lore.kernel.org/all/[email protected]/

 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?

Quoted 7 lines

Quoted 5 lines

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

Quoted 4 lines

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.

Quoted 3 lines

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