On Tue, 7 Feb 2023 at 03:30, 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. > > 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@xxxxxxx> > --- > 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@xxxxxxxxxx> 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:
smime.p7s
Description: S/MIME Cryptographic Signature
