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

[Jonathan Corbet]

Akira Yokosawa <akiyks@xxxxxxxxx> 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@xxxxxxxxx>
> Cc: Mauro Carvalho Chehab <mchehab@xxxxxxxxxx>

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