adding captions to left sidebar

Author: choldgraf

pydata_sphinx_theme/__init__.py

@@ -41,6 +41,7 @@ def get_nav_object(maxdepth=None, collapse=True, **kwargs):
         toctree = TocTree(app.env).get_toctree_for(
             pagename, app.builder, collapse=collapse, maxdepth=maxdepth, **kwargs
         )
+
         # If no toctree is defined (AKA a single-page site), skip this
         if toctree is None:
             return []
@@ -51,8 +52,14 @@ def get_nav_object(maxdepth=None, collapse=True, **kwargs):
         #       <list_item classes="toctree-l1">
         #       <list_item classes="toctree-l1">
         # `list_item`s are the actual TOC links and are the only thing we want
-        toc_items = [item for child in toctree.children for item in child
-                     if isinstance(item, docutils.nodes.list_item)]
+        toc_items = []
+        for child in toctree.children:
+            if isinstance(child, docutils.nodes.caption):
+                toc_items.append(child)
+            elif isinstance(child, docutils.nodes.bullet_list):
+                for list_entries in child:
+                    if isinstance(list_entries, docutils.nodes.list_item):
+                        toc_items.append(list_entries)
 
         # Now convert our docutils nodes into dicts that Jinja can use
         nav = [docutils_node_to_jinja(child, only_pages=True)
@@ -91,6 +98,12 @@ def docutils_node_to_jinja(list_item, only_pages=False):
         The TocTree, converted into a dictionary with key/values that work
         within Jinja.
     """
+    # If a caption, pass it through
+    if isinstance(list_item, docutils.nodes.caption):
+        nav = {"text": list_item.astext(), "type": "caption"}
+        return nav
+    
+    # Else, we assume it's a list item and need to parse the item content
     if not list_item.children:
         return None
 
@@ -112,6 +125,7 @@ def docutils_node_to_jinja(list_item, only_pages=False):
     nav["title"] = title
     nav["url"] = url
     nav["active"] = active
+    nav["type"] = "ref"
 
     # Recursively convert children as well
     # If there are sub-pages for this list_item, there should be two children:

pydata_sphinx_theme/docs-sidebar.html

@@ -10,10 +10,14 @@
   {% set nav = get_nav_object(maxdepth=3, collapse=True) %}
 
   <ul class="nav bd-sidenav">
+      <!-- top-level pages -->
       {% for main_nav_item in nav %}
       {% if main_nav_item.active %}
+        <!-- sub-pages within each top level page -->
         {% for nav_item in main_nav_item.children %}
-          {% if nav_item.children %}
+          {% if nav_item["type"] == "caption" %}
+            <li class="nav-caption">{{ nav_item.text }}</li>
+          {% elif nav_item.children %}
 
               <li class="{% if nav_item.active%}active{% endif %}">
                   <a href="{{ nav_item.url }}">{{ nav_item.title }}</a>