Re: New theme - Alabaster for Kernel Documentation

[Akira Yokosawa <akiyks@gmail.com>]

[+CC: konstantin]

Hi Sadiya,

On Wed, 18 Jan 2023 09:55:04 +0530, Sadiya Kazi wrote:
> Hi all,
> The design of the new "alabaster" theme used for Kernel documentation
> is nice and minimalistic, but I notice one issue with its navigational
> feature: In the "Alabaster" theme, the TOC appears at the top of the
> page. For documents with multiple headings, this design creates a
> usability issue by forcing the reader to scroll past a long TOC to get
> to the actual content. The previous "RTD" theme used a left navigation
> bar that allowed users to quickly navigate to the desired content.

I made a similar observation the other day.
I'm glad to know I was not alone. :-)

I've got a response from Jon.
See: https://lore.kernel.org/r/874jswyat3.fsf@meer.lwn.net/

Quote of Jon's words:

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

Returning to Sadiya's comment:

> 
> To try and compare both, please open the index page of the "alabaster"
> theme given below:
> https://www.kernel.org/doc/html/latest/dev-tools/index.html
> and the "RTD" theme given below:
> https://www.kernel.org/doc/html/v6.0-rc7/dev-tools/index.html
> and navigate to the KUnit page. You'll notice it takes more time to
> land on the KUnit page when using the alabaster theme.
> 
> With the "RTD" theme, the navigation sidebar links to other pages
> (parents, siblings, children, and all top-level pages) as shown below:
> https://www.kernel.org/doc/html/latest/dev-tools/kunit/index.html#

This link is identical to below. Did you mean

  https://www.kernel.org/doc/html/v6.0-rc7/dev-tools/kunit/index.html

?

> Alabaster only shows headings as shown below:
> https://www.kernel.org/doc/html/latest/dev-tools/kunit/index.html#
> making it effectively useless for navigation. This is particularly a
> problem for the KUnit documentation, which relies heavily on being
> able to find related pages. Currently to navigate to the related
> pages, the reader has to return to the Home page, use the search bar,
> or manually edit the URL (i.e, only if you know the chapter or section
> name).
> 
> So, after comparing both the themes, could we modify the sidebar to
> match the "rtd" behaviour if there is a way to do so?

As I mentioned in the above mentioned mail, there looks like a room
of customizing alabaster. Yet, I am not able to get a sidebar as usable
as that of sphinx_rtd_theme so far.

Maybe due to my inexperience in CSS customization. :-\

>                                                        If not, would it
> be sensible to either include this support in the "alabaster" theme or
> even temporarily roll back the change until we find a solution?
> 
> It'd be great to hear your thoughts on this.

sphinx_rtd_theme can be chosen by:

  make DOCS_THEME=sphinx_rtd_theme htmldocs

Konstantin, would it be possible for you to add "DOCS_THEME=sphinx_rtd_theme"
for the "latest" kernel documentation builds until the new default theme
becomes good enough for most people?  That is if Jon agrees.
For the "next" builds, alabaster theme should be OK, and easier for us to
compare the two themes.

        Thanks, Akira

> 
> Thanks,
> Sadiya