From 7c90840d616da4741424aa1c39acec477222f356 Mon Sep 17 00:00:00 2001
From: Matthias Geier <Matthias.Geier@gmail.com>
Date: Wed, 18 Jan 2023 19:09:50 +0100
Subject: [PATCH] DOC: Hide main TOC in <details>, add site usage instructions

---
 doc/conf.py   |  4 ++++
 doc/index.rst | 44 +++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 47 insertions(+), 1 deletion(-)

diff --git a/doc/conf.py b/doc/conf.py
index ff476d82..f5196378 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -187,3 +187,7 @@
         html_theme = 'insipid'
         html_copy_source = False
         html_permalinks_icon = '#'
+
+if globals().get('html_theme') == 'insipid':
+    # This controls optional content in index.rst:
+    tags.add('insipid')
diff --git a/doc/index.rst b/doc/index.rst
index 6c2693c3..c413c288 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -14,10 +14,14 @@ see :doc:`custom-formats` for details.
 
 __ https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
 
+.. raw:: html
+
+    <details>
+    <summary>click here to see full table of contents</summary>
+
 .. toctree::
     :maxdepth: 4
     :glob:
-    :hidden:
 
     installation
     usage
@@ -40,3 +44,41 @@ __ https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
 .. only:: html
 
     There is also :ref:`/orphan.ipynb`, just for the sake of it.
+
+.. raw:: html
+
+    </details>
+
+.. only:: html and insipid
+
+    .. admonition:: How To Navigate This Site
+
+        Use the *next* and *previous* links at the top and the bottom of each page
+        to flip through the pages.
+        Alternatively, you can use the right and left arrow keys
+        on your keyboard.
+        Some additional keyboard shortcuts
+        are provided via the `accesskey feature`__:
+        :kbd:`n` next,
+        :kbd:`p` previous,
+        :kbd:`u` up (= to the parent page),
+        :kbd:`i` index,
+        :kbd:`s` search and
+        :kbd:`m` menu (= open/close sidebar).
+
+        __ https://developer.mozilla.org/en-US/docs/
+            Web/HTML/Global_attributes/accesskey
+
+        Click on the `hamburger button`__ in the topbar
+        to open and close the sidebar.
+        The width of the sidebar can be adjusted by dragging its border.
+        Click on the title in the topbar to scroll to the top of the page,
+        if already at the top, go "up" to the parent page
+        (eventually ending up on this very page).
+
+        __ https://en.wikipedia.org/wiki/Hamburger_button
+
+        On *touch-enabled* devices:
+        Tap at the top of the page to show the topbar (if it was scrolled away);
+        swipe from the left edge to show the sidebar,
+        swipe towards the left to hide it.