[PATCH RFC] docs: Add more information to the HTML sidebar

[PATCH RFC] docs: Add more information to the HTML sidebar

[Jonathan Corbet]

Add a new sidebar template that creates a more RTD-like "fisheye" view of
the current place in the document hierarchy.  It is far from ideal, but
some readers may find it better for navigating through the documentation as
a whole.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
So this is just a first attempt to create a more crowded sidebar; the
result is somewhat like what RTD does; I'm not hugely happy with it, but
it's a start.

I've put a copy of the rendered docs at:

  https://static.lwn.net/kerneldoc/

Thoughts?  Is this headed in the right direction?  This view of the TOC
is readily available from Sphinx; if we want something else it's going
to be rather more work.

 Documentation/conf.py                          |  4 ++--
 Documentation/sphinx-static/custom.css         | 16 ++++++++++++++++
 Documentation/sphinx/templates/kernel-toc.html |  6 ++++++
 3 files changed, 24 insertions(+), 2 deletions(-)
 create mode 100644 Documentation/sphinx/templates/kernel-toc.html

diff --git a/Documentation/conf.py b/Documentation/conf.py
index d927737e3c10..233f2f585143 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -153,7 +153,7 @@ else:
     math_renderer = 'mathjax'
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ['sphinx/templates']
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
@@ -345,7 +345,7 @@ html_use_smartypants = False
 
 # Custom sidebar templates, maps document names to template names.
 # Note that the RTD theme ignores this
-html_sidebars = { '**': ['searchbox.html', 'localtoc.html', 'sourcelink.html']}
+html_sidebars = { '**': ['searchbox.html', 'kernel-toc.html', 'sourcelink.html']}
 
 # about.html is available for alabaster theme. Add it at the front.
 if html_theme == 'alabaster':
diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
index 45a624fdcf2c..1ad0899bc8f1 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -27,3 +27,19 @@ dl.function, dl.struct, dl.enum { margin-top: 2em; background-color: #ecf0f3; }
 dl.function dt { margin-left: 10em; text-indent: -10em; }
 dt.sig-object { font-size: larger; }
 div.kernelindent { margin-left: 2em; margin-right: 4em; }
+
+/*
+ * Tweaks for our local TOC
+ */
+div.kerneltoc li.toctree-l1 { font-size: smaller;
+		text-indent: -1em;
+		margin-left: 1em; }
+div.kerneltoc li.current {font-weight: bold; }
+div.kerneltoc li.toctree-l2 { font-size: smaller;
+		text-indent: -1em;
+		margin-left: 2em;
+		list-style-type: none;
+	      }
+div.kerneltoc li.current ul { margin-left: 0; }
+div.kerneltoc { background-color: #eeeeee; }
+div.kerneltoc li.current ul { background-color: white; }
diff --git a/Documentation/sphinx/templates/kernel-toc.html b/Documentation/sphinx/templates/kernel-toc.html
new file mode 100644
index 000000000000..0d2fa3748437
--- /dev/null
+++ b/Documentation/sphinx/templates/kernel-toc.html
@@ -0,0 +1,6 @@
+{# Create a local TOC the kernel way #}
+<p>
+<h3>Contents</h3>
+<div class="kerneltoc">
+{{ toctree(maxdepth=2) }}
+</div>
-- 
2.39.0

Re: [PATCH RFC] docs: Add more information to the HTML sidebar

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 1245 bytes --]

On Thu, Jan 19, 2023 at 05:11:20PM -0700, Jonathan Corbet wrote:
>  # Custom sidebar templates, maps document names to template names.
>  # Note that the RTD theme ignores this
> -html_sidebars = { '**': ['searchbox.html', 'localtoc.html', 'sourcelink.html']}
> +html_sidebars = { '**': ['searchbox.html', 'kernel-toc.html', 'sourcelink.html']}
>  

In the sidebar, I see process/ is misorganized. That is,
process/{development-process,submitting-patches,code-of-conduct}.html
are at top-level entry, although these should have been children of
process/.

> +
> +/*
> + * Tweaks for our local TOC
> + */
> +div.kerneltoc li.toctree-l1 { font-size: smaller;
> +		text-indent: -1em;
> +		margin-left: 1em; }
> +div.kerneltoc li.current {font-weight: bold; }
> +div.kerneltoc li.toctree-l2 { font-size: smaller;
> +		text-indent: -1em;
> +		margin-left: 2em;
> +		list-style-type: none;
> +	      }
> +div.kerneltoc li.current ul { margin-left: 0; }
> +div.kerneltoc { background-color: #eeeeee; }
> +div.kerneltoc li.current ul { background-color: white; }

I think only the visited page should be highlighted in bold, not its
full hierarchy.

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH RFC] docs: Add more information to the HTML sidebar

[Sadiya Kazi]

On Fri, Jan 20, 2023 at 5:41 AM Jonathan Corbet <corbet@lwn.net> wrote:
>
> Add a new sidebar template that creates a more RTD-like "fisheye" view of
> the current place in the document hierarchy.  It is far from ideal, but
> some readers may find it better for navigating through the documentation as
> a whole.
>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
Thank you, Jon.

This is definitely an improvement as we are able to see the second
level headings in the
sidebar of the main page. But I would still prefer the "RTD" theme
kind of sidebar due to the
following reasons:
- This sidebar toc list is not bulleted and the same chapter name runs
into multiple lines making
   it trickier for the reader to click the exact chapter they are interested in.
   Perhaps this can be handled by increasing the width of the sidebar.
This will avoid the
   chapter headings to go to the next line.
- Comprehending "where am I" is difficult. When I use the table of
contents to navigate
  to any chapter, such as https://static.lwn.net/kerneldoc/dev-
tools/kunit/architecture.html,
  I'm unsure of where to go from here because it's difficult to find
this chapter's exact location
  in the table of contents. Is there a way to get the nested headings
in the sidebar until
  depth 3 and make it collapsible?

Regards,
Sadiya





> So this is just a first attempt to create a more crowded sidebar; the
> result is somewhat like what RTD does; I'm not hugely happy with it, but
> it's a start.
>
> I've put a copy of the rendered docs at:
>
>   https://static.lwn.net/kerneldoc/
>
> Thoughts?  Is this headed in the right direction?  This view of the TOC
> is readily available from Sphinx; if we want something else it's going
> to be rather more work.
>
>  Documentation/conf.py                          |  4 ++--
>  Documentation/sphinx-static/custom.css         | 16 ++++++++++++++++
>  Documentation/sphinx/templates/kernel-toc.html |  6 ++++++
>  3 files changed, 24 insertions(+), 2 deletions(-)
>  create mode 100644 Documentation/sphinx/templates/kernel-toc.html
>
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index d927737e3c10..233f2f585143 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -153,7 +153,7 @@ else:
>      math_renderer = 'mathjax'
>
>  # Add any paths that contain templates here, relative to this directory.
> -templates_path = ['_templates']
> +templates_path = ['sphinx/templates']
>
>  # The suffix(es) of source filenames.
>  # You can specify multiple suffix as a list of string:
> @@ -345,7 +345,7 @@ html_use_smartypants = False
>
>  # Custom sidebar templates, maps document names to template names.
>  # Note that the RTD theme ignores this
> -html_sidebars = { '**': ['searchbox.html', 'localtoc.html', 'sourcelink.html']}
> +html_sidebars = { '**': ['searchbox.html', 'kernel-toc.html', 'sourcelink.html']}
>
>  # about.html is available for alabaster theme. Add it at the front.
>  if html_theme == 'alabaster':
> diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
> index 45a624fdcf2c..1ad0899bc8f1 100644
> --- a/Documentation/sphinx-static/custom.css
> +++ b/Documentation/sphinx-static/custom.css
> @@ -27,3 +27,19 @@ dl.function, dl.struct, dl.enum { margin-top: 2em; background-color: #ecf0f3; }
>  dl.function dt { margin-left: 10em; text-indent: -10em; }
>  dt.sig-object { font-size: larger; }
>  div.kernelindent { margin-left: 2em; margin-right: 4em; }
> +
> +/*
> + * Tweaks for our local TOC
> + */
> +div.kerneltoc li.toctree-l1 { font-size: smaller;
> +               text-indent: -1em;
> +               margin-left: 1em; }
> +div.kerneltoc li.current {font-weight: bold; }
> +div.kerneltoc li.toctree-l2 { font-size: smaller;
> +               text-indent: -1em;
> +               margin-left: 2em;
> +               list-style-type: none;
> +             }
> +div.kerneltoc li.current ul { margin-left: 0; }
> +div.kerneltoc { background-color: #eeeeee; }
> +div.kerneltoc li.current ul { background-color: white; }
> diff --git a/Documentation/sphinx/templates/kernel-toc.html b/Documentation/sphinx/templates/kernel-toc.html
> new file mode 100644
> index 000000000000..0d2fa3748437
> --- /dev/null
> +++ b/Documentation/sphinx/templates/kernel-toc.html
> @@ -0,0 +1,6 @@
> +{# Create a local TOC the kernel way #}
> +<p>
> +<h3>Contents</h3>
> +<div class="kerneltoc">
> +{{ toctree(maxdepth=2) }}
> +</div>
> --
> 2.39.0
>

Re: [PATCH RFC] docs: Add more information to the HTML sidebar

[Akira Yokosawa]

Hi all,

On Fri, 20 Jan 2023 19:08:14 +0530, Sadiya Kazi wrote:
> On Fri, Jan 20, 2023 at 5:41 AM Jonathan Corbet <corbet@lwn.net> wrote:
>>
>> Add a new sidebar template that creates a more RTD-like "fisheye" view of
>> the current place in the document hierarchy.  It is far from ideal, but
>> some readers may find it better for navigating through the documentation as
>> a whole.
>>
>> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
>> ---
> Thank you, Jon.
> 
> This is definitely an improvement as we are able to see the second
> level headings in the
> sidebar of the main page. But I would still prefer the "RTD" theme
> kind of sidebar due to the
> following reasons:
> - This sidebar toc list is not bulleted and the same chapter name runs
> into multiple lines making
>    it trickier for the reader to click the exact chapter they are interested in.
>    Perhaps this can be handled by increasing the width of the sidebar.
> This will avoid the
>    chapter headings to go to the next line.
> - Comprehending "where am I" is difficult. When I use the table of
> contents to navigate
>   to any chapter, such as https://static.lwn.net/kerneldoc/dev-
> tools/kunit/architecture.html,
>   I'm unsure of where to go from here because it's difficult to find
> this chapter's exact location
>   in the table of contents. Is there a way to get the nested headings
> in the sidebar until
>   depth 3 and make it collapsible?

I have mostly the same list of possible improvements.

As for the "where am I?" syndrome, it would be helpful if the sidebar
could be scrolled independently.

I'd really like to suggest some code changes, but unable to do so.

> 
> Regards,
> Sadiya
> 
> 
> 
> 
> 
>> So this is just a first attempt to create a more crowded sidebar; the
>> result is somewhat like what RTD does; I'm not hugely happy with it, but
>> it's a start.
>>
>> I've put a copy of the rendered docs at:
>>
>>   https://static.lwn.net/kerneldoc/
>>
>> Thoughts?  Is this headed in the right direction?  This view of the TOC
>> is readily available from Sphinx; if we want something else it's going
>> to be rather more work.

I think this looks like the right direction. But how far do you want to
mimic RTD's sidebar???

        Thanks, Akira

Re: [PATCH RFC] docs: Add more information to the HTML sidebar

[Jonathan Corbet]

Akira Yokosawa <akiyks@gmail.com> writes:

>>> Thoughts?  Is this headed in the right direction?  This view of the TOC
>>> is readily available from Sphinx; if we want something else it's going
>>> to be rather more work.
>
> I think this looks like the right direction. But how far do you want to
> mimic RTD's sidebar???

Well ... that is kind of my question for all of the folks who are
unhappy with the current sidebar.  What would you like to see there?

Things like sidebar width, whether bullets are used (I'd deliberately
taken them out as excess noise), which text is which color, etc. are all
just CSS; we can paint that shed any color we like.  The harder part is
deciding which information we want to have there in the first place.  So
... is the set of links shown in the new sidebar close to what we
want...  too much stuff?  Something missing?

Thanks,

jon

Re: [PATCH RFC] docs: Add more information to the HTML sidebar

[Akira Yokosawa]

On Fri, 20 Jan 2023 08:19:02 -0700, Jonathan Corbet wrote:
> Akira Yokosawa <akiyks@gmail.com> writes:
> 
>>>> Thoughts?  Is this headed in the right direction?  This view of the TOC
>>>> is readily available from Sphinx; if we want something else it's going
>>>> to be rather more work.
>>
>> I think this looks like the right direction. But how far do you want to
>> mimic RTD's sidebar???
> 
> Well ... that is kind of my question for all of the folks who are
> unhappy with the current sidebar.  What would you like to see there?
> 
> Things like sidebar width, whether bullets are used (I'd deliberately
> taken them out as excess noise), which text is which color, etc. are all
> just CSS; we can paint that shed any color we like.  The harder part is
> deciding which information we want to have there in the first place.  So
> ... is the set of links shown in the new sidebar close to what we
> want...  too much stuff?  Something missing?

Seeing no response from anyone so far, I feel like I need to express
my personal view. As you might already be well aware of, I love the
site navigation of RTD both on large screens and small (narrow) screens.

On *what* should be in the sidebar, I don't see anything missing
give or take the toctree depth.

To my eyes, there is two deficiencies with the alabaster theme in site
navigation.

  - Even with this RFC patch amended with the diff I suggested in
    https://lore.kernel.org/linux-doc/6b2e496f-d7f6-abea-6bbd-4b12fea76a68@gmail.com/,
    there remain "Where am I???" moments when jumping to a different page.
    In such jumps, alabaster's sidebar always reset to top with the
    main pane. RTD's sidebar keeps its position so there is no such
    moment.

  - On small/narrow screens, alabaster's sidebar is pushed downward
    to the bottom of the page. This means you typically need three
    steps to see where you are when jumping to another page:

      1) Jump to another page.
      2) Scroll to the bottom.
      3) See where you are.

    With RTD, you don't need to scroll to the bottom. Sidebar is there
    behind an icon at the top-left which is often used as "menu" icon.

      1) Jump to another page.
      2) Open sidebar and it tells you where you are.

I don't know if alabaster can be managed to behave similar to RTD
with a reasonable effort.

        Thanks, Akira


> 
> Thanks,
> 
> jon

Re: [PATCH RFC] docs: Add more information to the HTML sidebar

[Sadiya Kazi]

On Fri, Feb 3, 2023 at 8:07 AM Akira Yokosawa <akiyks@gmail.com> wrote:
>
> On Fri, 20 Jan 2023 08:19:02 -0700, Jonathan Corbet wrote:
> > Akira Yokosawa <akiyks@gmail.com> writes:
> >
> >>>> Thoughts?  Is this headed in the right direction?  This view of the TOC
> >>>> is readily available from Sphinx; if we want something else it's going
> >>>> to be rather more work.
> >>
> >> I think this looks like the right direction. But how far do you want to
> >> mimic RTD's sidebar???
> >
> > Well ... that is kind of my question for all of the folks who are
> > unhappy with the current sidebar.  What would you like to see there?
> >
> > Things like sidebar width, whether bullets are used (I'd deliberately
> > taken them out as excess noise), which text is which color, etc. are all
> > just CSS; we can paint that shed any color we like.  The harder part is
> > deciding which information we want to have there in the first place.  So
> > ... is the set of links shown in the new sidebar close to what we
> > want...  too much stuff?  Something missing?
>
> Seeing no response from anyone so far, I feel like I need to express
> my personal view. As you might already be well aware of, I love the
> site navigation of RTD both on large screens and small (narrow) screens.
>
(+1) to this. I too prefer the site navigation of RTD over Alabaster.

> On *what* should be in the sidebar, I don't see anything missing
> give or take the toctree depth.
>
> To my eyes, there is two deficiencies with the alabaster theme in site
> navigation.
>
>   - Even with this RFC patch amended with the diff I suggested in
>     https://lore.kernel.org/linux-doc/6b2e496f-d7f6-abea-6bbd-4b12fea76a68@gmail.com/,
>     there remain "Where am I???" moments when jumping to a different page.
>     In such jumps, alabaster's sidebar always reset to top with the
>     main pane. RTD's sidebar keeps its position so there is no such
>     moment.
>
>   - On small/narrow screens, alabaster's sidebar is pushed downward
>     to the bottom of the page. This means you typically need three
>     steps to see where you are when jumping to another page:
>
>       1) Jump to another page.
>       2) Scroll to the bottom.
>       3) See where you are.
>
>     With RTD, you don't need to scroll to the bottom. Sidebar is there
>     behind an icon at the top-left which is often used as "menu" icon.
>
>       1) Jump to another page.
>       2) Open sidebar and it tells you where you are.
>
Adding to what Akira says, what I really would like to see is a TOC in the
sidebar that shows all parts, with the current part expanded at all times.
For instance, the sidebar should expand and appear as follows when
I click the KUnit documentation's main index page:

KUnit - Linux Kernel Unit Testing
      Getting Started
      KUnit Architecture
      Run tests with KUnit
      Introduction
      Unit Testing

When the 'Introduction' item is  selected, the toc in the sidebar should get
updated as follows:

KUnit - Linux Kernel Unit Testing
Getting Started
KUnit Architecture
Run tests with KUnit
Introduction
    Features
    Prerequisites
Unit Testing

Currently, only the second-level headings exhibit the above behaviour,
as seen here:
https://static.lwn.net/kerneldoc/dev-tools/index.html

Applying this to third-level headings, which are significant in KUnit
docs, would be helpful.
It will make it easier for us to always know where we are
on this website because it displays the parent, sibling, and child
nodes of the current
page.

> I don't know if alabaster can be managed to behave similar to RTD
> with a reasonable effort.
>
>         Thanks, Akira
>
>
> >
> > Thanks,
> >
> > jon

Thanks,
Sadiya

Re: [PATCH RFC] docs: Add more information to the HTML sidebar

[Akira Yokosawa]

Hi Jon,

On Fri, 20 Jan 2023 23:09:34 +0900, Akira Yokosawa wrote:
...
> 
> I have mostly the same list of possible improvements.
> 
> As for the "where am I?" syndrome, it would be helpful if the sidebar
> could be scrolled independently.
> 
> I'd really like to suggest some code changes, but unable to do so.

There is a related question at stackoverflow [1].
The CSS tweak mentioned in its answer works like a charm.

Can you try the changes below on top of this RFC patch?

[1]: https://stackoverflow.com/questions/57031848/sphinx-alabaster-theme-scroll-inside-of-fixed-sidebar

        Thanks, Akira

-------------------------------
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 233f2f585143..6c8ccf3095ac 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -328,6 +328,7 @@ if  html_theme == 'alabaster':
         'description': get_cline_version(),
         'page_width': '65em',
         'sidebar_width': '15em',
+        'fixed_sidebar': 'true',
         'font_size': 'inherit',
         'font_family': 'serif',
     }
diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
index 1ad0899bc8f1..3ec27edeb394 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -11,7 +11,7 @@ div.body h3 { font-size: 130%; }
 /* Tighten up the layout slightly */
 div.body { padding: 0 15px 0 10px; }
 div.sphinxsidebarwrapper { padding: 1em 0.4em; }
-div.sphinxsidebar { font-size: inherit; }
+div.sphinxsidebar { font-size: inherit; max-height: 100%; overflow-y: auto; }
 /* Tweak document margins and don't force width */
 div.document {
     margin: 20px 10px 0 10px;