Re: [PATCH 1/5] docs: Switch the default HTML theme to alabaster

[Jani Nikula]

On Tue, 04 Oct 2022, Jonathan Corbet <corbet@xxxxxxx> 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@xxxxxxx>
> ---
>  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