Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <4b162dbe-2a7f-1710-93e0-754cf8680aae@gmail.com>
Date:   Tue, 10 Jan 2023 18:47:25 +0900
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101
 Thunderbird/102.4.2
Content-Language: en-US
To:     Jonathan Corbet <corbet@lwn.net>
Cc:     Mauro Carvalho Chehab <mchehab@kernel.org>,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        Akira Yokosawa <akiyks@gmail.com>
From:   Akira Yokosawa <akiyks@gmail.com>
Subject: [PATCH] docs/conf.py: Use about.html only in sidebar of alabaster
 theme
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk

"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@gmail.com>
Cc: Mauro Carvalho Chehab <mchehab@kernel.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