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

[Mauro Carvalho Chehab]

Em Tue,  4 Oct 2022 14:12:18 -0600
Jonathan Corbet <corbet@xxxxxxx> 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@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
> +
>  # 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