DOC: hide main index by default, add instructions

Author: mgeier

doc/conf.py

@@ -70,7 +70,7 @@
 
 html_show_copyright = False
 
-html_permalinks_icon = '§'
+html_permalinks_icon = '#'
 
 html_favicon = 'favicon.svg'
 

doc/index.rst

@@ -2,6 +2,11 @@
 
 ----
 
+.. raw:: html
+
+    <details>
+    <summary>click here to see full table of contents</summary>
+
 .. toctree::
 
    installation
@@ -15,3 +20,41 @@
 .. only:: html
 
    :ref:`genindex`
+
+.. raw:: html
+
+    </details>
+
+.. only:: html
+
+    .. 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.