adding support for multiple top-level headers

docs/demo/index.rst

@@ -16,6 +16,7 @@ the left sidebar to see how various elements look on this theme.
     lists_tables
     markdown
     example_pandas
+    mult_headers
 
 .. toctree::
     :maxdepth: 3

docs/demo/mult_headers.rst

@@ -0,0 +1,57 @@
+Top-level headers and the TOC
+=============================
+
+Your right table of contents will behave slightly differently depending on
+whether your page has one top-level header, or multiple top-level headers. See
+below for more information.
+
+An example with multiple top-level headers
+==========================================
+
+If a page has multiple top-level headers on it, then the in-page Table of Contents
+will show each top-level header.
+**On this page, there are multiple top-level headers**. As a result, the top-level
+headers all appear in the right Table of Contents. Here's an example of a page structure
+with multiple top-level headers:
+
+
+.. code-block:: rst
+
+   My first header
+   ===============
+
+   My sub-header
+   -------------
+
+   My second header
+   ================
+
+   My second sub-header
+   --------------------
+
+And here's a second-level header
+--------------------------------
+
+Notice how it is nested *underneath* "Top-level header 2" in the TOC.
+
+
+An example with a single top-level header
+=========================================
+
+If the page only has a single top-level header, it
+is assumed to be the page title, and only the headers **underneath** the top-level
+header will be used for the right Table of Contents.
+
+On most pages in this documentation, only a single top-level header is used. For
+example, they have a page structure like:
+
+.. code-block:: rst
+
+   My title
+   ========
+
+   My header
+   ---------
+
+   My second header
+   ----------------

pydata_sphinx_theme/__init__.py

@@ -65,7 +65,12 @@ def get_page_toc_object():
         self_toc = TocTree(app.env).get_toc_for(pagename, app.builder)
 
         try:
-            nav = docutils_node_to_jinja(self_toc.children[0])
+            # If there's only one child, assume we have a single "title" as top header
+            # so start the TOC at the first item's children (AKA, level 2 headers)
+            if len(self_toc.children) == 1:
+                nav = docutils_node_to_jinja(self_toc.children[0]).get("children", [])
+            else:
+                nav = [docutils_node_to_jinja(item) for item in self_toc.children]
             return nav
         except Exception:
             return {}

pydata_sphinx_theme/docs-toc.html

@@ -1,14 +1,14 @@
 {% set page_toc = get_page_toc_object() %}
 
-{%- if page_toc.children | length >= 1 %}
+{%- if page_toc | length >= 1 %}
 <div class="tocsection onthispage pt-5 pb-3">
     <i class="fas fa-list"></i> On this page
 </div>
 {%- endif %}
 
 <nav id="bd-toc-nav">
     <ul class="nav section-nav flex-column">
-    {% for item in page_toc.children recursive %}
+    {% for item in page_toc recursive %}
         <li class="nav-item toc-entry toc-h{{ loop.depth + 1 }}">
             <a href="{{ item.url }}" class="nav-link">{{ item.title }}</a>
         {%- if item.children -%}
@@ -21,4 +21,4 @@
     </ul>
 </nav>
 
-{% include "edit_this_page.html" %}
+{% include "edit_this_page.html" %}