Commit c404f5d4 authored by Jonathan Corbet's avatar Jonathan Corbet
Browse files

docs: Add more information to the HTML sidebar 



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.

Reviewed-by: default avatarAkira Yokosawa <akiyks@gmail.com>
Reviewed-by: default avatarDavid Gow <davidgow@google.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent fbabc2ea

Documentation/conf.py

+3 −2
Original line number Diff line number Diff line
@@ -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':

Documentation/sphinx-static/custom.css

+47 −1
Original line number Diff line number Diff line
@@ -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: small;

		text-indent: -1em;

		margin-left: 1em;

		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; }

}

Documentation/sphinx/templates/kernel-toc.html

0 → 100644
+16 −0
Original line number Diff line number Diff line 
{# SPDX-License-Identifier: GPL-2.0 #}

{# 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>