diff mbox series

docs/conf.py: Use about.html only in sidebar of alabaster theme

Message ID 4b162dbe-2a7f-1710-93e0-754cf8680aae@gmail.com
State New
Headers
Series docs/conf.py: Use about.html only in sidebar of alabaster theme |

Commit Message

Akira Yokosawa Jan. 10, 2023, 9:47 a.m. UTC 
  "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>
---
Hi Jon,

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?

        Thanks, Akira

--
 Documentation/conf.py | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)


base-commit: 7021e29503a30f323d74e91b57f06227337ecc95

Comments

Jonathan Corbet Jan. 11, 2023, 10:18 p.m. UTC | #1 
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
diff mbox series

Patch

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 44899be7b2cc..d927737e3c10 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -345,7 +345,11 @@  html_use_smartypants = False
 
 # Custom sidebar templates, maps document names to template names.
 # Note that the RTD theme ignores this
-html_sidebars = { '**': ["about.html", 'searchbox.html', 'localtoc.html', 'sourcelink.html']}
+html_sidebars = { '**': ['searchbox.html', 'localtoc.html', 'sourcelink.html']}
+
+# about.html is available for alabaster theme. Add it at the front.
+if html_theme == 'alabaster':
+    html_sidebars['**'].insert(0, 'about.html')
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'TheLinuxKerneldoc'