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
