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;
From:   Jonathan Corbet <corbet@lwn.net>
To:     Akira Yokosawa <akiyks@gmail.com>
Cc:     Mauro Carvalho Chehab <mchehab@kernel.org>,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        Akira Yokosawa <akiyks@gmail.com>
Subject: Re: [PATCH] docs/conf.py: Use about.html only in sidebar of
 alabaster theme
In-Reply-To: <4b162dbe-2a7f-1710-93e0-754cf8680aae@gmail.com>
References: <4b162dbe-2a7f-1710-93e0-754cf8680aae@gmail.com>
Date:   Wed, 11 Jan 2023 15:18:48 -0700
Message-ID: <874jswyat3.fsf@meer.lwn.net>
MIME-Version: 1.0
Content-Type: text/plain
Precedence: bulk

Akira Yokosawa <akiyks@gmail.com> writes:

> "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>

This seems like a good fix, applied, thanks.

> 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?

I picked it because it looked a lot cleaner than RTD, better supported
small-screen devices, and was the Sphinx default.  Like so many
things, it was done in a bit of a hurry and I cannot claim to have
thoroughly considered all of the alternatives.  I was hoping that people
would respond to the RFC if they had a better idea :)

If there is a better theme to use as the default, we can consider
changing it again; I don't think there is much cost or inconvenience
involved.  I do want the default theme to be one of those bundled with
Sphinx, though, rather than requiring it to be installed separately.

That said, I have no objection to adding configuration support for other
themes as well, should people want to use them.

Thanks,

jon