From f6c3d1d2cc38b53ba22f5890890a2d5db868a89d Mon Sep 17 00:00:00 2001
From: Marian Beermann <public@enkore.de>
Date: Fri, 30 Jun 2017 17:41:58 +0200
Subject: [PATCH] docs: no third level toc on command usage pages
 ("Description", "Examples")

---
 docs/_templates/globaltoc.html | 12 +++++++++++-
 docs/usage.rst                 |  2 --
 2 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/docs/_templates/globaltoc.html b/docs/_templates/globaltoc.html
index 7841437c..d10f5f77 100644
--- a/docs/_templates/globaltoc.html
+++ b/docs/_templates/globaltoc.html
@@ -1,6 +1,16 @@
 <div class="sidebar-block">
   <div class="sidebar-toc">
-    {% set toctree = toctree(maxdepth=3, collapse=True, includehidden=True) %}
+    {# Restrict the sidebar toc depth to two levels while generating command usage pages.
+       This avoids superfluous entries for each "Description" and "Examples" heading. #}
+    {% if pagename.startswith("usage/") and pagename not in (
+      "usage/general", "usage/help", "usage/debug", "usage/notes",
+    ) %}
+      {% set maxdepth = 2 %}
+    {% else %}
+      {% set maxdepth = 3 %}
+    {% endif %}
+
+    {% set toctree = toctree(maxdepth=maxdepth, collapse=True) %}
     {% if toctree %}
       {{ toctree }}
     {% else %}
diff --git a/docs/usage.rst b/docs/usage.rst
index 4f0419b4..de335c1c 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -31,8 +31,6 @@ Usage
    </script>
 
 .. toctree::
-   :hidden:
-
    usage/general
 
    usage/init