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

[PATCH RFC V2] 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>
---
Sorry it took so long to get back to this...$EXCUSES plus trying to get
ready for the merge window.

This version includes the suggestions Akira sent around a couple of
weeks ago.  I've also the sidebar TOC go one level deeper when
appropriate.

There's a bit of JavaScript that attempts to scroll the sidebar
appropriately.  It's far from perfect but, hopefully an improvement.  It
could be made better, but I've managed to remain blissfully ignorant of
JavaScript over the years, so it's slow going.  It would sure be nice if
somebody who is better at that stuff could jump in.

I think the contents of the sidebar could be improved too, but that's
probably a bigger job.

As before, the results can be seen at:

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

This probably isn't going to get a lot further before the merge window.
So I ask: is this sufficiently better that it should go into 6.3?  

 Documentation/conf.py                         |  5 +++--
 Documentation/sphinx-static/custom.css        | 20 ++++++++++++++++++-
 .../sphinx/templates/kernel-toc.html          | 11 ++++++++++
 3 files changed, 33 insertions(+), 3 deletions(-)
 create mode 100644 Documentation/sphinx/templates/kernel-toc.html

diff --git a/Documentation/conf.py b/Documentation/conf.py
index d927737e3c10..6c8ccf3095ac 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:
@@ -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',
     }
@@ -345,7 +346,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..17cc0abeb0a7 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -11,7 +11,9 @@ 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; 
@@ -27,3 +29,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,li.toctree-l3 { 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..020a174a8139
--- /dev/null
+++ b/Documentation/sphinx/templates/kernel-toc.html
@@ -0,0 +1,11 @@
+{# Create a local TOC the kernel way #}
+<p>
+<h3>Contents</h3>
+<div class="kerneltoc" id="kerneltoc">
+{{ toctree(maxdepth=3) }}
+</div>
+{# hacky script to try to position the left column #}
+<script type="text/javascript"> <!--
+  var sbar = document.getElementsByClassName("sphinxsidebar")[0];
+  sbar.scrollTop = document.getElementsByClassName("current")[0].offsetTop;
+  --> </script>
-- 
2.39.1

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

[Jonathan Corbet]

Jonathan Corbet <corbet@lwn.net> writes:

> As before, the results can be seen at:
>
>   https://static.lwn.net/kerneldoc/

What's there now reflects a couple of tweaks beyond the patch I sent.

Hopefully I've addressed some of the concerns...  One thing I really
don't like about the auto-positioning sidebar, though, is that it pushes
the "The Linux Kernel" heading off-screen.  For somebody following a
link into the docs from elsewhere, that could be a bit confusing.  I
know vaguely how to fix it with CSS, but getting such things right
always require a fair amount of dinking around and I can't do that now.

jon

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

[Randy Dunlap]

Hi Jonathan,

On 2/3/23 15:09, Jonathan Corbet 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>
> ---
> Sorry it took so long to get back to this...$EXCUSES plus trying to get
> ready for the merge window.
> 
> This version includes the suggestions Akira sent around a couple of
> weeks ago.  I've also the sidebar TOC go one level deeper when
> appropriate.
> 
> There's a bit of JavaScript that attempts to scroll the sidebar
> appropriately.  It's far from perfect but, hopefully an improvement.  It
> could be made better, but I've managed to remain blissfully ignorant of
> JavaScript over the years, so it's slow going.  It would sure be nice if
> somebody who is better at that stuff could jump in.
> 
> I think the contents of the sidebar could be improved too, but that's
> probably a bigger job.
> 
> As before, the results can be seen at:
> 
>   https://static.lwn.net/kerneldoc/

I haven't been following this saga closely but this is looking good to me.
Thanks.

Nit: it says that it's for kernel 6.2.0-rc2-6.2.0-rc2+.
Is that expected?

Another question: if I'm deep into the menu tree, is there a way (link) to get
back to the top level?  Other than editing the URL, that is.


> This probably isn't going to get a lot further before the merge window.
> So I ask: is this sufficiently better that it should go into 6.3?  

I'll let the others answer that one.

>  Documentation/conf.py                         |  5 +++--
>  Documentation/sphinx-static/custom.css        | 20 ++++++++++++++++++-
>  .../sphinx/templates/kernel-toc.html          | 11 ++++++++++
>  3 files changed, 33 insertions(+), 3 deletions(-)
>  create mode 100644 Documentation/sphinx/templates/kernel-toc.html

-- 
~Randy

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

[Akira Yokosawa]

On Fri, 03 Feb 2023 17:02:17 -0700, Jonathan Corbet wrote:
> Jonathan Corbet <corbet@lwn.net> writes:
> 
>> As before, the results can be seen at:
>>
>>   https://static.lwn.net/kerneldoc/
> 
> What's there now reflects a couple of tweaks beyond the patch I sent.
> 
> Hopefully I've addressed some of the concerns...  One thing I really
> don't like about the auto-positioning sidebar, though, is that it pushes
> the "The Linux Kernel" heading off-screen.  For somebody following a
> link into the docs from elsewhere, that could be a bit confusing.

That's the same in RTD. So this might be a point you hate RTD, I guess.

But I see a major problem on small/narrow screens.
The sidebar is now kept at the top, and by clicking/tapping a link in the
TOC, I can't jump to the section I want to see.

Sorry, but this is not usable at all.

>                                                                    I
> know vaguely how to fix it with CSS, but getting such things right
> always require a fair amount of dinking around and I can't do that now.

;-) ;-) ;-)

        Thanks, Akira

> 
> jon

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

[David Gow]

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

On Sat, 4 Feb 2023 at 07:10, 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>
> ---
> Sorry it took so long to get back to this...$EXCUSES plus trying to get
> ready for the merge window.
>
> This version includes the suggestions Akira sent around a couple of
> weeks ago.  I've also the sidebar TOC go one level deeper when
> appropriate.
>
> There's a bit of JavaScript that attempts to scroll the sidebar
> appropriately.  It's far from perfect but, hopefully an improvement.  It
> could be made better, but I've managed to remain blissfully ignorant of
> JavaScript over the years, so it's slow going.  It would sure be nice if
> somebody who is better at that stuff could jump in.
>
> I think the contents of the sidebar could be improved too, but that's
> probably a bigger job.
>
> As before, the results can be seen at:
>
>   https://static.lwn.net/kerneldoc/
>
> This probably isn't going to get a lot further before the merge window.
> So I ask: is this sufficiently better that it should go into 6.3?
>

This is much better, thanks!

Personally, I think this fixes the problems I had with the earlier
alabaster versions. It's still not quite perfect, but it's usable to
me in a way the original versions weren't.

There are definitely a few pages which are nested even deeper than
maxdepth=3, which become more difficult to navigate, but they seem
rare enough that it might make more sense to just restructure those
bits of the docs to remove some levels of nesting.

Otherwise, mostly small css issues (the main one being the font size
for the 3rd level nested elements being way too small to comfortably
read). Getting rid of the font-size: smaller bit works for me. In fact
(at least for my normal usage pattern), the more deeply nested
something is, the more useful it's likely to be: navigating to child
and/or sibling pages (or back to the immediate parent page) is most
common, as those pages are most related. So having the font size
increase with "font-size: larger" actually works pretty well, even if
it really gives a weirdly-bulging "fisheye" view to everything.

I still think RTD is a bit more usable at the moment, if only because
of the higher contrast and the breadcrumbs at the top of each page.
But this is good enough that I can get everywhere I need to go without
constantly needing to use the browser back button. So I'd much rather
this in 6.3 than the stock alabaster version, even if it could still
use some tweaks.

Cheers,
-- David

>  Documentation/conf.py                         |  5 +++--
>  Documentation/sphinx-static/custom.css        | 20 ++++++++++++++++++-
>  .../sphinx/templates/kernel-toc.html          | 11 ++++++++++
>  3 files changed, 33 insertions(+), 3 deletions(-)
>  create mode 100644 Documentation/sphinx/templates/kernel-toc.html
>
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index d927737e3c10..6c8ccf3095ac 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:
> @@ -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',
>      }
> @@ -345,7 +346,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..17cc0abeb0a7 100644
> --- a/Documentation/sphinx-static/custom.css
> +++ b/Documentation/sphinx-static/custom.css
> @@ -11,7 +11,9 @@ 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;
> @@ -27,3 +29,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,li.toctree-l3 { 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..020a174a8139
> --- /dev/null
> +++ b/Documentation/sphinx/templates/kernel-toc.html
> @@ -0,0 +1,11 @@
> +{# Create a local TOC the kernel way #}
> +<p>
> +<h3>Contents</h3>
> +<div class="kerneltoc" id="kerneltoc">
> +{{ toctree(maxdepth=3) }}
> +</div>
> +{# hacky script to try to position the left column #}
> +<script type="text/javascript"> <!--
> +  var sbar = document.getElementsByClassName("sphinxsidebar")[0];
> +  sbar.scrollTop = document.getElementsByClassName("current")[0].offsetTop;
> +  --> </script>
> --
> 2.39.1
>

[-- Attachment #2: S/MIME Cryptographic Signature --]
[-- Type: application/pkcs7-signature, Size: 4003 bytes --]

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

[Akira Yokosawa]

On Date: Sat, 4 Feb 2023 09:20:13 +0900, Akira Yokosawa wrote:
> On Fri, 03 Feb 2023 17:02:17 -0700, Jonathan Corbet wrote:
>> Jonathan Corbet <corbet@lwn.net> writes:
>>
>>> As before, the results can be seen at:
>>>
>>>   https://static.lwn.net/kerneldoc/
>>
>> What's there now reflects a couple of tweaks beyond the patch I sent.
>>
>> Hopefully I've addressed some of the concerns...  One thing I really
>> don't like about the auto-positioning sidebar, though, is that it pushes
>> the "The Linux Kernel" heading off-screen.  For somebody following a
>> link into the docs from elsewhere, that could be a bit confusing.
> 
> That's the same in RTD. So this might be a point you hate RTD, I guess.
> 
> But I see a major problem on small/narrow screens.
> The sidebar is now kept at the top, and by clicking/tapping a link in the
> TOC, I can't jump to the section I want to see.
> 
> Sorry, but this is not usable at all.

To be clear, I meant "on small/narrow screens".
On normal PC screens, this resolves the issues I mentioned earlier.

So I'm OK with this goes into v6.3. Maybe add a note on small screen
devices in the Changelog.

BTW, I very much like the way LWN's site navigation behaves on small
screen devices. LWN is designed to be accessible without hierarchical
structure of documents, which is the opposite of how kernel documentation
is managed based on the nested TOC entries.

        Thanks, Akira

> 
>>                                                                    I
>> know vaguely how to fix it with CSS, but getting such things right
>> always require a fair amount of dinking around and I can't do that now.
> 
> ;-) ;-) ;-)
> 
>         Thanks, Akira
> 
>>
>> jon

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

[Jonathan Corbet]

Akira Yokosawa <akiyks@gmail.com> writes:

>> But I see a major problem on small/narrow screens.
>> The sidebar is now kept at the top, and by clicking/tapping a link in the
>> TOC, I can't jump to the section I want to see.
>> 
>> Sorry, but this is not usable at all.
>
> To be clear, I meant "on small/narrow screens".
> On normal PC screens, this resolves the issues I mentioned earlier.
>
> So I'm OK with this goes into v6.3. Maybe add a note on small screen
> devices in the Changelog.

I see what you're saying.

The best solution to this, I guess, would be to hide the contents menu
behind an icon in the small-screen view.  Doable, I'll try to find some
time to make that happen.

> BTW, I very much like the way LWN's site navigation behaves on small
> screen devices. LWN is designed to be accessible without hierarchical
> structure of documents, which is the opposite of how kernel documentation
> is managed based on the nested TOC entries.

Yeah, but for the kernel documentation the hierarchy is the only
structure we have.  Making less of a mess out of it has been a many-year
project, got a long way to go...

Thanks,

jon

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

[Sadiya Kazi]

On Sat, Feb 4, 2023 at 4:40 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>
> ---
> Sorry it took so long to get back to this...$EXCUSES plus trying to get
> ready for the merge window.
>
> This version includes the suggestions Akira sent around a couple of
> weeks ago.  I've also the sidebar TOC go one level deeper when
> appropriate.
>
> There's a bit of JavaScript that attempts to scroll the sidebar
> appropriately.  It's far from perfect but, hopefully an improvement.  It
> could be made better, but I've managed to remain blissfully ignorant of
> JavaScript over the years, so it's slow going.  It would sure be nice if
> somebody who is better at that stuff could jump in.
>
> I think the contents of the sidebar could be improved too, but that's
> probably a bigger job.
>
> As before, the results can be seen at:
>
>   https://static.lwn.net/kerneldoc/
>
> This probably isn't going to get a lot further before the merge window.
> So I ask: is this sufficiently better that it should go into 6.3?

Thank you very much, Jon. This version looks better than the previous one
and resolves the "Where am I?" problem. As David suggested, the font size
for the third-level nested heading in the sidebar should be increased;
otherwise, it
is good to go for 6.3.

Regards,
Sadiya



>
>  Documentation/conf.py                         |  5 +++--
>  Documentation/sphinx-static/custom.css        | 20 ++++++++++++++++++-
>  .../sphinx/templates/kernel-toc.html          | 11 ++++++++++
>  3 files changed, 33 insertions(+), 3 deletions(-)
>  create mode 100644 Documentation/sphinx/templates/kernel-toc.html
>
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index d927737e3c10..6c8ccf3095ac 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:
> @@ -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',
>      }
> @@ -345,7 +346,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..17cc0abeb0a7 100644
> --- a/Documentation/sphinx-static/custom.css
> +++ b/Documentation/sphinx-static/custom.css
> @@ -11,7 +11,9 @@ 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;
> @@ -27,3 +29,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,li.toctree-l3 { 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..020a174a8139
> --- /dev/null
> +++ b/Documentation/sphinx/templates/kernel-toc.html
> @@ -0,0 +1,11 @@
> +{# Create a local TOC the kernel way #}
> +<p>
> +<h3>Contents</h3>
> +<div class="kerneltoc" id="kerneltoc">
> +{{ toctree(maxdepth=3) }}
> +</div>
> +{# hacky script to try to position the left column #}
> +<script type="text/javascript"> <!--
> +  var sbar = document.getElementsByClassName("sphinxsidebar")[0];
> +  sbar.scrollTop = document.getElementsByClassName("current")[0].offsetTop;
> +  --> </script>
> --
> 2.39.1
>

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

[Jonathan Corbet]

Randy Dunlap <rdunlap@infradead.org> writes:

> Nit: it says that it's for kernel 6.2.0-rc2-6.2.0-rc2+.
> Is that expected?

Um ... no.  That won't be the result of my current changes, but I'll
look into it.

> Another question: if I'm deep into the menu tree, is there a way
> (link) to get back to the top level?  Other than editing the URL, that
> is.

Click on "The Linux Kernel" at the top of the sidebar.

Thanks,

jon

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

[Randy Dunlap]

Hi Jonathan,

On 2/6/23 11:25, Jonathan Corbet wrote:
> Randy Dunlap <rdunlap@infradead.org> writes:
> 
>> Nit: it says that it's for kernel 6.2.0-rc2-6.2.0-rc2+.
>> Is that expected?
> 
> Um ... no.  That won't be the result of my current changes, but I'll
> look into it.
> 
>> Another question: if I'm deep into the menu tree, is there a way
>> (link) to get back to the top level?  Other than editing the URL, that
>> is.
> 
> Click on "The Linux Kernel" at the top of the sidebar.

Ah. That works. :)

Is there a reason that the main index's "sections" (single underline)
don't show up in the sidebar index?  Is that on purpose?
Or just a relic of them being "sections"?

(Why are they sections? Why is the main document's title a chapter
instead of being the Document title?)

I would like to be able to see visually when the sidebar index goes from
one "section" to another one, e.g., from "Internal API manuals"
to "Development tools and processes". I think that there might be a
small blank (like 1/2 line space) between these sections now, but
that is easy to overlook.

Thanks for listening.
-- 
~Randy

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

[Jonathan Corbet]

Randy Dunlap <rdunlap@infradead.org> writes:

> Is there a reason that the main index's "sections" (single underline)
> don't show up in the sidebar index?  Is that on purpose?
> Or just a relic of them being "sections"?

That's just how the sidebar gets generated.  I would much rather see the
sections there...but if we want that, I think we'll have to implement it
ourselves.

> (Why are they sections? Why is the main document's title a chapter
> instead of being the Document title?)

Good question...that's just how it was done.  Probably worth fixing.

> I would like to be able to see visually when the sidebar index goes from
> one "section" to another one, e.g., from "Internal API manuals"
> to "Development tools and processes". I think that there might be a
> small blank (like 1/2 line space) between these sections now, but
> that is easy to overlook.

See above :)

Thanks,

jon

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

[Akira Yokosawa]

Hi,

On Tue, 14 Feb 2023 11:33:09 -0700, Jonathan Corbet wrote:
> Randy Dunlap <rdunlap@infradead.org> writes:
> 
>> Is there a reason that the main index's "sections" (single underline)
>> don't show up in the sidebar index?  Is that on purpose?
>> Or just a relic of them being "sections"?
> 
> That's just how the sidebar gets generated.  I would much rather see the
> sections there...but if we want that, I think we'll have to implement it
> ourselves.

I'd say that the reason why you don't see sections of the main index in
the sidebar is because the main index.rst *isn't* listed in any of
"toctree" directives.

So, if you want those "sections" in the sidebar, you need to create
a .rst file and list it in a toctree of main index.

The RTD theme has exactly the same behavior ever since commit
0c7b4366f1ab ("docs: Rewrite the front page").
Furthermore, as there are quite a few pages which belong to multiple
toctrees, sidebar sometimes behaves weirdly.

For example, see the sidebar at:

   https://www.kernel.org/doc/html/next/process/submitting-patches.html
                                         (built on current linux-next)

You will see that the "Submitting patches ..." title is expanded
twice in the sidebar.

Don't you think this looks weird? ;-)

I think the patch appended below (on top of current docs-next)
would have been a better approach, where each .rst file is listed
only once in the whole toctree. The refurbished part of main index
is moved to index-frequent.rst and toctrees are replaced with
lists of :doc: references.

Per-directory indexes are listed in the main index's toctree
below the index-frequent.

I'm not saying this is "the" right approach.
There can be many ways to accomplish the same result, I suppose.

I'll submit this change as a proper patch if I can get positive
feedback.

Hope this helps.

        Thanks, Akira

------------------
diff --git a/Documentation/index-frequent.rst b/Documentation/index-frequent.rst
new file mode 100644
index 000000000000..5d412be69196
--- /dev/null
+++ b/Documentation/index-frequent.rst
@@ -0,0 +1,75 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===============================
+Frequently Referenced Documents
+===============================
+
+This is a list of links to kernel documents which would help
+(prospective) kernel developers most.
+
+Working with the development community
+======================================
+
+The essential guides for interacting with the kernel's development
+community and getting your work upstream.
+
+ * process/development-process.rst
+ * process/submitting-patches.rst
+ * :doc:`Code of condust <process/code-of-conduct>`
+ * maintainer/index.rst
+ * :doc:`All development-process docs <process/index>`
+
+
+Internal API manuals
+====================
+
+Manuals for use by developers working to interface with the rest of the
+kernel.
+
+ * core-api/index.rst
+ * driver-api/index.rst
+ * subsystems-apis/index.rst
+ * :doc:`Locking in the kernel <locking/index>`
+
+
+Development tools and processes
+===============================
+
+Various other manuals with useful information for all kernel developers.
+
+ * process/license-rules.rst
+ * doc-guide/index.rst
+ * dev-tools/index.rst
+ * dev-tools/testing-overview.rst
+ * kernel-hacking/index.rst
+ * trace/index.rst
+ * fault-injection/index.rst
+ * livepatch/index.rst
+ * rust/index.rst
+
+
+User-oriented documentation
+===========================
+
+The following manuals are written for *users* of the kernel — those who are
+trying to get it to work optimally on a given system and application
+developers seeking information on the kernel's user-space APIs.
+
+ * admin-guide/index.rst
+ * :doc:`The kernel build system <kbuild/index>`
+ * admin-guide/reporting-issues.rst
+ * :doc:`User-space tools <tools/index>`
+ *  userspace-api/index.rst
+
+See also: the `Linux man pages <https://www.kernel.org/doc/man-pages/>`_,
+which are kept separately from the kernel's own documentation.
+
+
+Firmware-related documentation
+==============================
+
+The following holds information on the kernel's expectations regarding the
+platform firmwares.
+
+ * firmware-guide/index.rst
+ * devicetree/index.rst
diff --git a/Documentation/index.rst b/Documentation/index.rst
index bf6aa681c960..a50681452fab 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -12,86 +12,41 @@ documents into a coherent whole.  Please note that improvements to the
 documentation are welcome; join the linux-doc list at vger.kernel.org if
 you want to help out.
 
-Working with the development community
---------------------------------------
-
-The essential guides for interacting with the kernel's development
-community and getting your work upstream.
-
 .. toctree::
-   :maxdepth: 1
-
-   process/development-process
-   process/submitting-patches
-   Code of conduct <process/code-of-conduct>
-   maintainer/index
-   All development-process docs <process/index>
+   :maxdepth: 2
 
+   index-frequent
 
-Internal API manuals
---------------------
 
-Manuals for use by developers working to interface with the rest of the
-kernel.
+Per-subdirectory documents (referenced from above)
+--------------------------------------------------
 
 .. toctree::
    :maxdepth: 1
 
+   process/index
+   maintainer/index
    core-api/index
    driver-api/index
    subsystem-apis
-   Locking in the kernel <locking/index>
-
-Development tools and processes
--------------------------------
-
-Various other manuals with useful information for all kernel developers.
-
-.. toctree::
-   :maxdepth: 1
+   locking/index
 
-   process/license-rules
    doc-guide/index
    dev-tools/index
-   dev-tools/testing-overview
    kernel-hacking/index
    trace/index
    fault-injection/index
    livepatch/index
    rust/index
 
-
-User-oriented documentation
----------------------------
-
-The following manuals are written for *users* of the kernel — those who are
-trying to get it to work optimally on a given system and application
-developers seeking information on the kernel's user-space APIs.
-
-.. toctree::
-   :maxdepth: 1
-
    admin-guide/index
-   The kernel build system <kbuild/index>
-   admin-guide/reporting-issues.rst
-   User-space tools <tools/index>
+   kbuild/index
+   tools/index
    userspace-api/index
 
-See also: the `Linux man pages <https://www.kernel.org/doc/man-pages/>`_,
-which are kept separately from the kernel's own documentation.
-
-Firmware-related documentation
-------------------------------
-The following holds information on the kernel's expectations regarding the
-platform firmwares.
-
-.. toctree::
-   :maxdepth: 1
-
    firmware-guide/index
    devicetree/index
 
-
 Architecture-specific documentation
 -----------------------------------
 
@@ -123,6 +78,6 @@ Translations
    translations/index
 
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
-- 

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

[Jonathan Corbet]

Akira Yokosawa <akiyks@gmail.com> writes:

> I think the patch appended below (on top of current docs-next)
> would have been a better approach, where each .rst file is listed
> only once in the whole toctree. The refurbished part of main index
> is moved to index-frequent.rst and toctrees are replaced with
> lists of :doc: references.
>
> Per-directory indexes are listed in the main index's toctree
> below the index-frequent.
>
> I'm not saying this is "the" right approach.
> There can be many ways to accomplish the same result, I suppose.
>
> I'll submit this change as a proper patch if I can get positive
> feedback.

So I applied this and built it.  There may be potential in this
approach, but I don't think we are there yet.

This change completely loses the organization that I wanted to put onto
the front page itself.  That page will be the place where people land
first, so it should guide them to somewhere useful as quickly and easily
as possible.  With this change, we've hidden that guidance in a
subsidiary page and the front is back to a random collection of
unordered stuff.

The front page, I think, is more important than the sidebar.

We really need to look into the actual generation of the sidebar; it's
on my list, but won't happen before the merge window.  I do appreciate
playing with ideas, though - please keep it up!  We'll figure out
something eventually...:)

Thanks,

jon