The read-the-docs theme is not entirely attractive and doesn't give us
control over the left column.  "Alabaster" is deemed the default Sphinx
theme, it is currently maintained and shipped bundled with Sphinx itself,
so there is no need to install it separately.  Switch over to this theme as
the default for building kernel documentation; the DOCS_THEME environment
variable can still be used to select a different theme.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/conf.py | 26 ++++++++++++++++++++++++--
 1 file changed, 24 insertions(+), 2 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 22c9d4df1967..629f4afeb0eb 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -194,6 +194,24 @@ finally:
     else:
         version = release = "unknown version"
 
+#
+# HACK: there seems to be no easy way for us to get at the version and
+# release information passed in from the makefile...so go pawing through the
+# command-line options and find it for ourselves.
+#
+def get_cline_version():
+    c_version = c_release = ''
+    for arg in sys.argv:
+        if arg.startswith('version='):
+            c_version = arg[8:]
+        elif arg.startswith('release='):
+            c_release = arg[8:]
+    if c_version:
+        if c_release:
+            return c_version + '-' + c_release
+        return c_version
+    return version # Whatever we came up with before
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
@@ -247,7 +265,7 @@ highlight_language = 'none'
 # a list of builtin themes.
 
 # Default theme
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'alabaster'
 html_css_files = []
 
 if "DOCS_THEME" in os.environ:
@@ -324,6 +342,10 @@ if  html_theme == 'classic':
         'bodyfont':            "serif",
         'headfont':            "sans-serif",
     }
+else:
+    html_theme_options = {
+        'description': get_cline_version(),
+    }
 
 sys.stderr.write("Using %s theme\n" % html_theme)
 
@@ -371,7 +393,7 @@ html_use_smartypants = False
 
 # Custom sidebar templates, maps document names to template names.
 # Note that the RTD theme ignores this
-html_sidebars = { '**': ['searchbox.html', 'localtoc.html', 'sourcelink.html']}
+html_sidebars = { '**': ["about.html", 'searchbox.html', 'localtoc.html', 'sourcelink.html']}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
-- 
2.37.2

Em Tue,  4 Oct 2022 14:12:18 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> The read-the-docs theme is not entirely attractive and doesn't give us
> control over the left column.  "Alabaster" is deemed the default Sphinx
> theme, it is currently maintained and shipped bundled with Sphinx itself,
> so there is no need to install it separately.  Switch over to this theme as
> the default for building kernel documentation; the DOCS_THEME environment
> variable can still be used to select a different theme.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
>  Documentation/conf.py | 26 ++++++++++++++++++++++++--
>  1 file changed, 24 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 22c9d4df1967..629f4afeb0eb 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -194,6 +194,24 @@ finally:
>      else:
>          version = release = "unknown version"
>  
> +#
> +# HACK: there seems to be no easy way for us to get at the version and
> +# release information passed in from the makefile...so go pawing through the
> +# command-line options and find it for ourselves.
> +#
> +def get_cline_version():
> +    c_version = c_release = ''
> +    for arg in sys.argv:
> +        if arg.startswith('version='):
> +            c_version = arg[8:]
> +        elif arg.startswith('release='):
> +            c_release = arg[8:]
> +    if c_version:
> +        if c_release:
> +            return c_version + '-' + c_release
> +        return c_version
> +    return version # Whatever we came up with before
> +
>  # The language for content autogenerated by Sphinx. Refer to documentation
>  # for a list of supported languages.
>  #
> @@ -247,7 +265,7 @@ highlight_language = 'none'
>  # a list of builtin themes.
>  
>  # Default theme
> -html_theme = 'sphinx_rtd_theme'
> +html_theme = 'alabaster'
>  html_css_files = []

You should probably touch other parts of conf.py as well, folding your
patch 1 with the enclosed diff - or some variant of it.

Basically, the current logic is to try RTD. If not found, fall back to
classic (which is also a native theme), customizing it a little bit to
look closer to the way RTD outputs the sidebars, and adjusting some colors
to make it look nicer.

Regards,
Mauro

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 934727e23e0e..87f821287908 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -241,7 +241,7 @@ if html_theme == 'sphinx_rtd_theme' or html_theme == 'sphinx_rtd_dark_mode':
                 html_css_files.append('theme_rtd_colors.css')
 
     except ImportError:
-        html_theme = 'classic'
+        html_theme = 'alabaster'
 
 if "DOCS_CSS" in os.environ:
     css = os.environ["DOCS_CSS"].split(" ")
@@ -257,36 +257,6 @@ 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

On Tue, 04 Oct 2022, Jonathan Corbet <corbet@lwn.net> wrote:
> The read-the-docs theme is not entirely attractive and doesn't give us
> control over the left column.  "Alabaster" is deemed the default Sphinx
> theme, it is currently maintained and shipped bundled with Sphinx itself,
> so there is no need to install it separately.  Switch over to this theme as
> the default for building kernel documentation; the DOCS_THEME environment
> variable can still be used to select a different theme.
>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
>  Documentation/conf.py | 26 ++++++++++++++++++++++++--
>  1 file changed, 24 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 22c9d4df1967..629f4afeb0eb 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -194,6 +194,24 @@ finally:
>      else:
>          version = release = "unknown version"
>  
> +#
> +# HACK: there seems to be no easy way for us to get at the version and
> +# release information passed in from the makefile...so go pawing through the
> +# command-line options and find it for ourselves.
> +#
> +def get_cline_version():
> +    c_version = c_release = ''
> +    for arg in sys.argv:
> +        if arg.startswith('version='):
> +            c_version = arg[8:]
> +        elif arg.startswith('release='):
> +            c_release = arg[8:]
> +    if c_version:
> +        if c_release:
> +            return c_version + '-' + c_release
> +        return c_version
> +    return version # Whatever we came up with before
> +

This is a bit sad. There should be a way to set the description in the
theme template at a later time, when version is available. This is how
the rtd theme does it [1].

Would only need to inject one line in the template html, but I don't
know how to do that. :(

I wonder if the right way to do this would be to define our own theme,
which would mostly just extend alabaster, but would have small tweaks
[2]. Where are the Jinja experts when you need one?!


BR,
Jani.


[1] https://github.com/readthedocs/sphinx_rtd_theme/blob/master/sphinx_rtd_theme/layout.html#L150
[2] https://www.sphinx-doc.org/en/master/templating.html

>  # The language for content autogenerated by Sphinx. Refer to documentation
>  # for a list of supported languages.
>  #
> @@ -247,7 +265,7 @@ highlight_language = 'none'
>  # a list of builtin themes.
>  
>  # Default theme
> -html_theme = 'sphinx_rtd_theme'
> +html_theme = 'alabaster'
>  html_css_files = []
>  
>  if "DOCS_THEME" in os.environ:
> @@ -324,6 +342,10 @@ if  html_theme == 'classic':
>          'bodyfont':            "serif",
>          'headfont':            "sans-serif",
>      }
> +else:
> +    html_theme_options = {
> +        'description': get_cline_version(),
> +    }
>  
>  sys.stderr.write("Using %s theme\n" % html_theme)
>  
> @@ -371,7 +393,7 @@ html_use_smartypants = False
>  
>  # Custom sidebar templates, maps document names to template names.
>  # Note that the RTD theme ignores this
> -html_sidebars = { '**': ['searchbox.html', 'localtoc.html', 'sourcelink.html']}
> +html_sidebars = { '**': ["about.html", 'searchbox.html', 'localtoc.html', 'sourcelink.html']}
>  
>  # Additional templates that should be rendered to pages, maps page names to
>  # template names.

-- 
Jani Nikula, Intel Open Source Graphics Center

Jani Nikula <jani.nikula@linux.intel.com> writes:

> I wonder if the right way to do this would be to define our own theme,
> which would mostly just extend alabaster, but would have small tweaks
> [2]. Where are the Jinja experts when you need one?!
>
> [2] https://www.sphinx-doc.org/en/master/templating.html

I've pondered just creating our own theme, it's not *that* hard to do.
It's another thing to maintain across multiple sphinx versions, though.
I'd be more enthusiastic about the idea if we had a $SOMEBODY who would
commit to doing that.

Thanks,

jon

Em Wed, 05 Oct 2022 11:49:33 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Jani Nikula <jani.nikula@linux.intel.com> writes:
> 
> > I wonder if the right way to do this would be to define our own theme,
> > which would mostly just extend alabaster, but would have small tweaks
> > [2]. Where are the Jinja experts when you need one?!
> >
> > [2] https://www.sphinx-doc.org/en/master/templating.html  
> 
> I've pondered just creating our own theme, it's not *that* hard to do.
> It's another thing to maintain across multiple sphinx versions, though.

Yeah, that can be painful. Btw, at least on Fedora, RTD dark theme is
not working anymore (perhaps because Python 3.10 - the extension announces
it up to python 3.9).

I suspect that maintaining our own theme will require extra efforts to
workaround with per-version ABIs that keep changing on both Python and
Sphinx sides.

> I'd be more enthusiastic about the idea if we had a $SOMEBODY who would
> commit to doing that.
> 
> Thanks,
> 
> jon