New theme - Alabaster for Kernel Documentation

New theme - Alabaster for Kernel Documentation

[Sadiya Kazi]

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.

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

Thanks,
Sadiya

Re: New theme - Alabaster for Kernel Documentation

[Akira Yokosawa]

[+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

Re: New theme - Alabaster for Kernel Documentation

[Jonathan Corbet]

Akira Yokosawa <akiyks@gmail.com> writes:

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

I'd prefer to avoid this if possible.  In the end, though, what
kernel.org does isn't my decision, of course...  but if the Alabaster
mode is really that bad, we should either fix it or just revert the
change.  I'll try to dig into the sidebar generation a bit, but time is
scarce.

Before going too far, what exactly is the desired sidebar experience
here?  I find the RTD approach, which keeps all of the top-level entries
there, to be severely messy and would prefer not to reproduce it.  Of
course, some of that reflects the still-messy nature of our top-level
Documentation/ directory, another thing I'd like to fix.

Thanks,

jon

Re: New theme - Alabaster for Kernel Documentation

[Konstantin Ryabitsev]

On Thu, Jan 19, 2023 at 02:29:21PM -0700, Jonathan Corbet wrote:
> Akira Yokosawa <akiyks@gmail.com> writes:
> 
> > 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.
> 
> I'd prefer to avoid this if possible.  In the end, though, what
> kernel.org does isn't my decision, of course...

Something I've considered is to have /latest/ show the latest mainline
*released* mainline, while /rc/ would show the latest rc. So, we'd have three
distinct movable targets:

docs.kernel.org       - latest mainline release (same as kernel.org/doc/html/latest/)
docs.kernel.org/next/ - linux-next
docs.kernel.org/rc/   - latest rc

Would that be acceptable as a solution?

-K

Re: New theme - Alabaster for Kernel Documentation

[Jonathan Corbet]

Konstantin Ryabitsev <konstantin@linuxfoundation.org> writes:

> On Thu, Jan 19, 2023 at 02:29:21PM -0700, Jonathan Corbet wrote:
>> Akira Yokosawa <akiyks@gmail.com> writes:
>> 
>> > 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.
>> 
>> I'd prefer to avoid this if possible.  In the end, though, what
>> kernel.org does isn't my decision, of course...
>
> Something I've considered is to have /latest/ show the latest mainline
> *released* mainline, while /rc/ would show the latest rc. So, we'd have three
> distinct movable targets:
>
> docs.kernel.org       - latest mainline release (same as kernel.org/doc/html/latest/)
> docs.kernel.org/next/ - linux-next
> docs.kernel.org/rc/   - latest rc
>
> Would that be acceptable as a solution?

I think we've miscommunicated somewhere.  What I don't like is the idea
of building the mainline docs with a non-default HTML theme.

A "latest -rc" build could be a nice thing, though :)

Thanks,

jon

Re: New theme - Alabaster for Kernel Documentation

[Konstantin Ryabitsev]

On Thu, Jan 19, 2023 at 02:55:18PM -0700, Jonathan Corbet wrote:
> >> I'd prefer to avoid this if possible.  In the end, though, what
> >> kernel.org does isn't my decision, of course...
> >
> > Something I've considered is to have /latest/ show the latest mainline
> > *released* mainline, while /rc/ would show the latest rc. So, we'd have three
> > distinct movable targets:
> >
> > docs.kernel.org       - latest mainline release (same as kernel.org/doc/html/latest/)
> > docs.kernel.org/next/ - linux-next
> > docs.kernel.org/rc/   - latest rc
> >
> > Would that be acceptable as a solution?
> 
> I think we've miscommunicated somewhere.  What I don't like is the idea
> of building the mainline docs with a non-default HTML theme.

We haven't really miscommunicated -- I'm just giving an option that solves
things right now (and gives everyone time to roll back to a different theme if
it's deemed needed for the v6.2 release).

> A "latest -rc" build could be a nice thing, though :)

OK, I'll see if I can add that in.

-K