[PATCH RFC] docs: Add more information to the HTML sidebar

[Jonathan Corbet <corbet@lwn.net>]

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@lwn.net>
---
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