linux-kernel - Re: [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-prev] [day] [month] [year] [list]

Message-ID: <874jswyat3.fsf@meer.lwn.net>
Date:   Wed, 11 Jan 2023 15:18:48 -0700
From:   Jonathan Corbet <corbet@....net>
To:     Akira Yokosawa <akiyks@...il.com>
Cc:     Mauro Carvalho Chehab <mchehab@...nel.org>,
        linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
        Akira Yokosawa <akiyks@...il.com>
Subject: Re: [PATCH] docs/conf.py: Use about.html only in sidebar of
 alabaster theme

Akira Yokosawa <akiyks@...il.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@...il.com>
> Cc: Mauro Carvalho Chehab <mchehab@...nel.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