On Sat, 4 Feb 2023 at 07:10, 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> > --- > 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:
smime.p7s
Description: S/MIME Cryptographic Signature
