On Fri, Jan 20, 2023 at 5:41 AM Jonathan Corbet <corbet@xxxxxxx> 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@xxxxxxx> > --- 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 >
