[PATCH v3] docs: improve the HTML sidebar/TOC

[PATCH v3] docs: improve the HTML sidebar/TOC

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

Add some CSS trickery as well to make the table of contents less intrusive
when viewing the pages on a small screen.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
Changes this time are almost entirely in the small-screen view; I've
added some CSS trickery to hide the TOC by default so it doesn't get
between readers and what they actually want to see.  I'm sure it could
be done more elegantly, but my fluency with CSS ... does not afford much
elegance ...

Once again, the results are at:

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

This is as far as this work is likely to get before the merge window; in
the absence of screams, I'll drop it into linux-next in the near future.

 Documentation/conf.py                         |  5 +-
 Documentation/sphinx-static/custom.css        | 48 ++++++++++++++++++-
 .../sphinx/templates/kernel-toc.html          | 15 ++++++
 3 files changed, 65 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..539577ac9baa 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,47 @@ 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 > a {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; }
+
+/*
+ * The CSS magic to toggle the contents on small screens.
+ */
+label.kernel-toc-title { display: none; }
+label.kernel-toc-title:after {
+    content: "[Hide]";
+}
+input[type=checkbox]:checked ~ label.kernel-toc-title:after {
+    content: "[Show]";
+}
+/* Hide the toggle on large screens */
+input.kernel-toc-toggle { display: none; }
+
+/*
+ * Show and implement the toggle on small screens.
+ * The 875px width seems to be wired into alabaster.
+ */
+@media screen and (max-width: 875px) {
+    label.kernel-toc-title { display: inline;
+			     font-weight: bold;
+			     font-size: larger; }
+    input[type=checkbox]:checked ~ div.kerneltoc {
+	display: none;
+    }
+    h3.kernel-toc-contents { display: inline; }
+    div.kerneltoc a { color: black; }
+}
diff --git a/Documentation/sphinx/templates/kernel-toc.html b/Documentation/sphinx/templates/kernel-toc.html
new file mode 100644
index 000000000000..b124f6cfa558
--- /dev/null
+++ b/Documentation/sphinx/templates/kernel-toc.html
@@ -0,0 +1,15 @@
+{# Create a local TOC the kernel way #}
+<p>
+<h3 class="kernel-toc-contents">Contents</h3>
+<input type="checkbox" class="kernel-toc-toggle" id = "kernel-toc-toggle" checked>
+<label class="kernel-toc-title" for="kernel-toc-toggle"></label>
+
+<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];
+  let currents = document.getElementsByClassName("current")
+  sbar.scrollTop = currents[currents.length - 1].offsetTop;
+  --> </script>
-- 
2.39.1

Re: [PATCH v3] docs: improve the HTML sidebar/TOC

[Akira Yokosawa]

Hi Jon,

On Mon, 06 Feb 2023 12:30:02 -0700, 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.
> 
> Add some CSS trickery as well to make the table of contents less intrusive
> when viewing the pages on a small screen.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
> Changes this time are almost entirely in the small-screen view; I've
> added some CSS trickery to hide the TOC by default so it doesn't get
> between readers and what they actually want to see.  I'm sure it could
> be done more elegantly, but my fluency with CSS ... does not afford much
> elegance ...
> 
> Once again, the results are at:
> 
>   https://static.lwn.net/kerneldoc/

It took a few seconds for me to figure out the TOC entries are hidden
behind the "[Show]". Yes, this works reasonably well.

Thank you for your efforts.

Reviewed-by: Akira Yokosawa <akiyks@gmail.com>

        Thanks, Akira 

> 
> This is as far as this work is likely to get before the merge window; in
> the absence of screams, I'll drop it into linux-next in the near future.
> 
>  Documentation/conf.py                         |  5 +-
>  Documentation/sphinx-static/custom.css        | 48 ++++++++++++++++++-
>  .../sphinx/templates/kernel-toc.html          | 15 ++++++
>  3 files changed, 65 insertions(+), 3 deletions(-)
>  create mode 100644 Documentation/sphinx/templates/kernel-toc.html
> 

Re: [PATCH v3] docs: improve the HTML sidebar/TOC

[David Gow]

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

On Tue, 7 Feb 2023 at 03:30, 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.
>
> Add some CSS trickery as well to make the table of contents less intrusive
> when viewing the pages on a small screen.
>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
> Changes this time are almost entirely in the small-screen view; I've
> added some CSS trickery to hide the TOC by default so it doesn't get
> between readers and what they actually want to see.  I'm sure it could
> be done more elegantly, but my fluency with CSS ... does not afford much
> elegance ...
>
> Once again, the results are at:
>
>   https://static.lwn.net/kerneldoc/
>
> This is as far as this work is likely to get before the merge window; in
> the absence of screams, I'll drop it into linux-next in the near future.
>

Thanks for these fixes!

This now looks good to me, modulo the font size being too small for
nested toc entries.

I'm sure there are lots of other improvements that can be made, but
this isn't causing me any issues, so (with the font size fixed) this
is
Reviewed-by: David Gow <davidgow@google.com>

Cheers,
-- David

>  Documentation/conf.py                         |  5 +-
>  Documentation/sphinx-static/custom.css        | 48 ++++++++++++++++++-
>  .../sphinx/templates/kernel-toc.html          | 15 ++++++
>  3 files changed, 65 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..539577ac9baa 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,47 @@ 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 > a {font-weight: bold; }
> +div.kerneltoc li.toctree-l2,li.toctree-l3 { font-size: smaller;

Can we remove the font-size: smaller here (and _maybe_ above for toctree-l1)?

toctree-l3 ends up at ~9.259pt grey-on-white font here, which is
basically an unreadable grey blur.

> +               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; }
> +
> +/*
> + * The CSS magic to toggle the contents on small screens.
> + */
> +label.kernel-toc-title { display: none; }
> +label.kernel-toc-title:after {
> +    content: "[Hide]";
> +}
> +input[type=checkbox]:checked ~ label.kernel-toc-title:after {
> +    content: "[Show]";
> +}
> +/* Hide the toggle on large screens */
> +input.kernel-toc-toggle { display: none; }
> +
> +/*
> + * Show and implement the toggle on small screens.
> + * The 875px width seems to be wired into alabaster.
> + */
> +@media screen and (max-width: 875px) {
> +    label.kernel-toc-title { display: inline;
> +                            font-weight: bold;
> +                            font-size: larger; }
> +    input[type=checkbox]:checked ~ div.kerneltoc {
> +       display: none;
> +    }
> +    h3.kernel-toc-contents { display: inline; }
> +    div.kerneltoc a { color: black; }
> +}
> diff --git a/Documentation/sphinx/templates/kernel-toc.html b/Documentation/sphinx/templates/kernel-toc.html
> new file mode 100644
> index 000000000000..b124f6cfa558
> --- /dev/null
> +++ b/Documentation/sphinx/templates/kernel-toc.html
> @@ -0,0 +1,15 @@
> +{# Create a local TOC the kernel way #}
> +<p>
> +<h3 class="kernel-toc-contents">Contents</h3>
> +<input type="checkbox" class="kernel-toc-toggle" id = "kernel-toc-toggle" checked>
> +<label class="kernel-toc-title" for="kernel-toc-toggle"></label>
> +
> +<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];
> +  let currents = document.getElementsByClassName("current")
> +  sbar.scrollTop = currents[currents.length - 1].offsetTop;
> +  --> </script>
> --
> 2.39.1
>

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

Re: [PATCH v3] docs: improve the HTML sidebar/TOC

[Sadiya Kazi]

On Tue, Feb 7, 2023 at 1:00 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.
>
> Add some CSS trickery as well to make the table of contents less intrusive
> when viewing the pages on a small screen.
>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
> Changes this time are almost entirely in the small-screen view; I've
> added some CSS trickery to hide the TOC by default so it doesn't get
> between readers and what they actually want to see.  I'm sure it could
> be done more elegantly, but my fluency with CSS ... does not afford much
> elegance ...
>
> Once again, the results are at:
>
>   https://static.lwn.net/kerneldoc/
>
> This is as far as this work is likely to get before the merge window; in
> the absence of screams, I'll drop it into linux-next in the near future.

Thanks Jon! This looks fine to me. Although the font size in the nested
headings could be increased slightly. But for the time being, this is
sufficient.

Reviewed-by: Sadiya Kazi <sadiyakazi@google.com>

Regards,
Sadiya Kazi
>
>  Documentation/conf.py                         |  5 +-
>  Documentation/sphinx-static/custom.css        | 48 ++++++++++++++++++-
>  .../sphinx/templates/kernel-toc.html          | 15 ++++++
>  3 files changed, 65 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..539577ac9baa 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,47 @@ 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 > a {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; }
> +
> +/*
> + * The CSS magic to toggle the contents on small screens.
> + */
> +label.kernel-toc-title { display: none; }
> +label.kernel-toc-title:after {
> +    content: "[Hide]";
> +}
> +input[type=checkbox]:checked ~ label.kernel-toc-title:after {
> +    content: "[Show]";
> +}
> +/* Hide the toggle on large screens */
> +input.kernel-toc-toggle { display: none; }
> +
> +/*
> + * Show and implement the toggle on small screens.
> + * The 875px width seems to be wired into alabaster.
> + */
> +@media screen and (max-width: 875px) {
> +    label.kernel-toc-title { display: inline;
> +                            font-weight: bold;
> +                            font-size: larger; }
> +    input[type=checkbox]:checked ~ div.kerneltoc {
> +       display: none;
> +    }
> +    h3.kernel-toc-contents { display: inline; }
> +    div.kerneltoc a { color: black; }
> +}
> diff --git a/Documentation/sphinx/templates/kernel-toc.html b/Documentation/sphinx/templates/kernel-toc.html
> new file mode 100644
> index 000000000000..b124f6cfa558
> --- /dev/null
> +++ b/Documentation/sphinx/templates/kernel-toc.html
> @@ -0,0 +1,15 @@
> +{# Create a local TOC the kernel way #}
> +<p>
> +<h3 class="kernel-toc-contents">Contents</h3>
> +<input type="checkbox" class="kernel-toc-toggle" id = "kernel-toc-toggle" checked>
> +<label class="kernel-toc-title" for="kernel-toc-toggle"></label>
> +
> +<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];
> +  let currents = document.getElementsByClassName("current")
> +  sbar.scrollTop = currents[currents.length - 1].offsetTop;
> +  --> </script>
> --
> 2.39.1
>