linux-kernel - [PATCH] docs/conf.py: Use about.html only in sidebar of alabaster theme

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite for Android: free password hash cracker in your pocket

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-ID: <4b162dbe-2a7f-1710-93e0-754cf8680aae@gmail.com>
Date:   Tue, 10 Jan 2023 18:47:25 +0900
From:   Akira Yokosawa <akiyks@...il.com>
To:     Jonathan Corbet <corbet@....net>
Cc:     Mauro Carvalho Chehab <mchehab@...nel.org>,
        linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
        Akira Yokosawa <akiyks@...il.com>
Subject: [PATCH] docs/conf.py: Use about.html only in sidebar of alabaster
 theme

"about.html" is available only for the alabaster theme [1].
Unconditionally putting it to html_sidebars prevents us from
using other themes which respect html_sidebars.

Remove about.html from the initialization and insert it at the
front for the alabaster theme.

Link: [1] https://alabaster.readthedocs.io/en/latest/installation.html#sidebars
Fixes: d5389d3145ef ("docs: Switch the default HTML theme to alabaster")
Signed-off-by: Akira Yokosawa <akiyks@...il.com>
Cc: Mauro Carvalho Chehab <mchehab@...nel.org>
---
Hi Jon,

I noticed this (kind of) build regression while trying to compare
the alabaster theme with the other themes.

I must say that the current html documentation at

    https://www.kernel.org/doc/html/latest/

is almost unusable in site navigation. Once I jump from the top page
to somewhere, I'm at a loss. I can only go back to the top page,
or go back to the previous page with the help of the browser. 
(Of course, as I know the directory structure under Documentation/,
I can navigate manually, but that's not nice!)
I think it should at least have the same set of links as those
the classic theme provides.

Having read [1] and its surrounding documentation (for the first time,
I must confess), the alabaster theme sounds (somewhat) unique in
customizing sidebar and related links.

But before looking further into alabaster, I'd like to know why
you picked alabaster among those themes which come with Sphinx.
Could you elaborate?

        Thanks, Akira

--
 Documentation/conf.py | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 44899be7b2cc..d927737e3c10 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -345,7 +345,11 @@ html_use_smartypants = False

 # Custom sidebar templates, maps document names to template names.
 # Note that the RTD theme ignores this
-html_sidebars = { '**': ["about.html", 'searchbox.html', 'localtoc.html', 'sourcelink.html']}
+html_sidebars = { '**': ['searchbox.html', 'localtoc.html', 'sourcelink.html']}
+
+# about.html is available for alabaster theme. Add it at the front.
+if html_theme == 'alabaster':
+    html_sidebars['**'].insert(0, 'about.html')

 # Output file base name for HTML help builder.
 htmlhelp_basename = 'TheLinuxKerneldoc'

base-commit: 7021e29503a30f323d74e91b57f06227337ecc95
-- 
2.25.1