Commit c404f5d4 authored by Jonathan Corbet's avatar Jonathan Corbet

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: David Gow <davidgow@google.com
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent fbabc2ea
...@@ -153,7 +153,7 @@ else: ...@@ -153,7 +153,7 @@ else:
math_renderer = 'mathjax' math_renderer = 'mathjax'
# Add any paths that contain templates here, relative to this directory. # Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates'] templates_path = ['sphinx/templates']
# The suffix(es) of source filenames. # The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string: # You can specify multiple suffix as a list of string:
...@@ -328,6 +328,7 @@ if html_theme == 'alabaster': ...@@ -328,6 +328,7 @@ if html_theme == 'alabaster':
'description': get_cline_version(), 'description': get_cline_version(),
'page_width': '65em', 'page_width': '65em',
'sidebar_width': '15em', 'sidebar_width': '15em',
'fixed_sidebar': 'true',
'font_size': 'inherit', 'font_size': 'inherit',
'font_family': 'serif', 'font_family': 'serif',
} }
...@@ -345,7 +346,7 @@ html_use_smartypants = False ...@@ -345,7 +346,7 @@ html_use_smartypants = False
# Custom sidebar templates, maps document names to template names. # Custom sidebar templates, maps document names to template names.
# Note that the RTD theme ignores this # 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. # about.html is available for alabaster theme. Add it at the front.
if html_theme == 'alabaster': if html_theme == 'alabaster':
......
...@@ -11,7 +11,9 @@ div.body h3 { font-size: 130%; } ...@@ -11,7 +11,9 @@ div.body h3 { font-size: 130%; }
/* Tighten up the layout slightly */ /* Tighten up the layout slightly */
div.body { padding: 0 15px 0 10px; } div.body { padding: 0 15px 0 10px; }
div.sphinxsidebarwrapper { padding: 1em 0.4em; } 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 */ /* Tweak document margins and don't force width */
div.document { div.document {
margin: 20px 10px 0 10px; margin: 20px 10px 0 10px;
...@@ -27,3 +29,47 @@ dl.function, dl.struct, dl.enum { margin-top: 2em; background-color: #ecf0f3; } ...@@ -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; } dl.function dt { margin-left: 10em; text-indent: -10em; }
dt.sig-object { font-size: larger; } dt.sig-object { font-size: larger; }
div.kernelindent { margin-left: 2em; margin-right: 4em; } 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; }
}
{# 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>
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment