improving caption headers

docs/index.md

@@ -21,7 +21,6 @@ notebooks
 ## Reference pages
 
 ```{toctree}
-:divider:
 :caption: Reference items
 demochapter1/index
 limits

docs/layout.md

@@ -201,8 +201,3 @@ To make all sub-pages of the left Table of Contents expanded, add `:expand_secti
 
 If you'd like to add a header above a section of TOC links, use `:caption: My header text`
 in your `toctree` directive for that section.
-
-### Add a divider to your TOC
-
-If you'd like to add a divider above a section of TOC links, use `:divider:`
-in your `toctree` directive for that section.

sphinx_book_theme/__init__.py

@@ -3,7 +3,9 @@
 import docutils
 from myst_nb.parser import CellNode
 from docutils.parsers.rst import directives
+from docutils import nodes
 from sphinx.util import logging
+from sphinx import addnodes
 from sphinx.directives.other import TocTree
 from sphinx.util.nodes import explicit_title_re
 import sass
@@ -12,8 +14,6 @@
 SPHINX_LOGGER = logging.getLogger(__name__)
 EXTRA_TOC_OPTIONS = {
     "expand_sections": directives.flag,
-    "caption": directives.unchanged_required,
-    "divider": directives.flag,
 }
 
 
@@ -85,6 +85,15 @@ def lookup_extra_toc(pagename, extra_toc_list, kind="parent"):
                 if str(pagename) == lookup_page:
                     return val
 
+        # Figure out the top-lever pages that need a TOC in front of them
+        master_toctrees = app.env.tocs[app.env.config['master_doc']]
+        toc_captions = []
+        for master_toctree in master_toctrees.traverse(addnodes.toctree):
+            if master_toctree.attributes.get("caption"):
+                caption = master_toctree.attributes.get("caption")
+                toctree_first_page = master_toctree.attributes['entries'][0][1]  # Entries are (title, ref) pairs
+                toc_captions.append((toctree_first_page, caption))
+
         ul = [f'<ul class="nav sidenav_l{level}">']
         # If we don't include parents, next `ul` should be the same level
         next_level = level + 1 if include_item_names else level
@@ -93,20 +102,17 @@ def lookup_extra_toc(pagename, extra_toc_list, kind="parent"):
             if (child is None) or not (include_item_names or child["children"]):
                 continue
 
-            # Add captions and dividers if so-given
+            # Add captions if so-given
             page_rel_root = find_url_relative_to_root(
                 pagename, child["url"], app.srcdir
             )
-            divider = lookup_extra_toc(page_rel_root, extra_toc["divider"], "child")
-            caption = lookup_extra_toc(page_rel_root, extra_toc["caption"], "child")
-            if any((divider, caption)):
-                ul.append('<li class="sidebar-special">')
-                if divider:
-                    ul.append("<hr />")
-                if caption:
-                    # TODO: whenever pydata-sphinx-theme gets support for captions, we should just use that and remove this
-                    ul.append(f'<p class="sidebar-caption">{caption}</p>')
-                ul.append("</li>")
+            for caption_page, caption_text in toc_captions:
+                if caption_page == str(page_rel_root):
+                    ul.append('<li class="sidebar-special">')
+                    if caption:
+                        # TODO: whenever pydata-sphinx-theme gets support for captions, we should just use that and remove this
+                        ul.append(f'<p class="sidebar-caption">{caption_text}</p>')
+                    ul.append("</li>")
 
             # Now begin rendering the links
             active = "active" if child["active"] else ""
@@ -212,6 +218,7 @@ def compile_scss():
 
 
 class NewTocTree(TocTree):
+    """A monkey-patch of the TocTree so we can intercept extra keywords without raising Sphinx errors."""
     newtoctree_spec = TocTree.option_spec.copy()
     newtoctree_spec.update(EXTRA_TOC_OPTIONS)
     option_spec = newtoctree_spec

sphinx_book_theme/static/jupyterbook.css

@@ -243,10 +243,11 @@ button.topbarbtn img {
     overflow: hidden;
     position: relative;
     padding-top: 0; }
+  .bd-sidebar li + li.sidebar-special {
+    margin-top: 1em; }
   .bd-sidebar p.sidebar-caption {
     margin-bottom: 0;
-    font-weight: bold;
-    font-size: 1.1em; }
+    font-size: 1.2em; }
 
 .site-navigation, .site-navigation.collapsing {
   transition: flex .2s ease 0s, height .35s ease, opacity 0.2s ease; }

sphinx_book_theme/static/jupyterbook.scss

@@ -382,11 +382,16 @@ button.topbarbtn img {
         padding-top: 0;
     }
 
+    // Captions
+    li + li.sidebar-special {
+        margin-top: 1em;
+    }
+
     p.sidebar-caption {
         margin-bottom: 0;
-        font-weight: bold;
-        font-size: 1.1em;
+        font-size: 1.2em;
     }
+
 }
 
 .site-navigation, .site-navigation.collapsing {