cherrypick: Add TOC expand-collapse icons (#664)

bmunkholm · bmunkholm · commit 371595e3f8eb · 2026-01-08T09:24:17.000+01:00
diff --git a/.gitignore b/.gitignore
@@ -21,3 +21,4 @@ dist
 eggs
 node_modules*
 yarn-error.log
+_*
diff --git a/docs/index.rst b/docs/index.rst
@@ -57,17 +57,17 @@ The legacy feature gallery exclusively uses reStructuredText.
 .. toctree::
     :maxdepth: 1
 
+    headings
     admonitions
     codesnippets
-    diagrams
-    glossary
-    headings
-    images
     lists
-    projects
-    subpage
     tables
+    images
+    diagrams
     typography
+    subpage
+    projects
+    tests/index
 
 
 
diff --git a/docs/tests/glossary.rst b/docs/tests/glossary.rst
diff --git a/docs/tests/index.rst b/docs/tests/index.rst
@@ -0,0 +1,23 @@
+.. _tests:
+
+#########################
+Navigation bar test pages
+#########################
+
+1. Clicking the title should expand the section and navigate to the section page
+2. Clicking just the icon should expand but not navigate to the section
+3. Clicking just the icon for an expanded section should collapse that section and leave other expanded sections expanded
+4. Hovering the mouse over an icon should show a fade background behind the icon
+5. Hovering the mouse over the title should show a fade background behind the title and the icon
+6. The current page should be highlighted in the navigation bar as the user navigates through the pages below.
+
+
+**Pages:**
+
+.. toctree::
+    :titlesonly:
+    :glob:
+
+    section1/index
+    section2/index
+    *
diff --git a/docs/tests/section1/index.rst b/docs/tests/section1/index.rst
@@ -0,0 +1,9 @@
+#########
+Section 1
+#########
+
+.. toctree::
+   :maxdepth: 1
+
+   subpage1
+   subpage2
diff --git a/docs/tests/section1/subpage1.rst b/docs/tests/section1/subpage1.rst
@@ -0,0 +1,5 @@
+##########
+Subpage 1
+##########
+
+Test subpage 1.
diff --git a/docs/tests/section1/subpage2.rst b/docs/tests/section1/subpage2.rst
@@ -0,0 +1,5 @@
+##########
+Subpage 2
+##########
+
+Test subpage 2.
diff --git a/docs/tests/section2/index.rst b/docs/tests/section2/index.rst
@@ -0,0 +1,12 @@
+############
+Section 2
+############
+
+.. toctree::
+   :maxdepth: 1
+
+   section21/index
+   subpage1
+   subpage2
+
+Hi
diff --git a/docs/tests/section2/section21/index.rst b/docs/tests/section2/section21/index.rst
@@ -0,0 +1,9 @@
+############
+Section 2.1
+############
+
+.. toctree::
+   :maxdepth: 1
+
+   subpage1
+   subpage2
diff --git a/docs/tests/section2/section21/subpage1.rst b/docs/tests/section2/section21/subpage1.rst
@@ -0,0 +1,5 @@
+##########
+Subpage 1
+##########
+
+Test subpage 1.
diff --git a/docs/tests/section2/section21/subpage2.rst b/docs/tests/section2/section21/subpage2.rst
@@ -0,0 +1,5 @@
+##########
+Subpage 2
+##########
+
+Test subpage 2.
diff --git a/docs/tests/section2/subpage1.rst b/docs/tests/section2/subpage1.rst
@@ -0,0 +1,5 @@
+##########
+Subpage 1
+##########
+
+Test subpage 1.
diff --git a/docs/tests/section2/subpage2.rst b/docs/tests/section2/subpage2.rst
@@ -0,0 +1,5 @@
+##########
+Subpage 2
+##########
+
+Test subpage 2.
diff --git a/src/crate/theme/rtd/__init__.py b/src/crate/theme/rtd/__init__.py
@@ -22,6 +22,7 @@
 """CrateDB Sphinx theme for Read the Docs"""
 
 import os
+from .sidebartoc import generate_crate_navigation_html
 
 VERSION = (0, 45, 0)
 
@@ -32,27 +33,47 @@
 def get_version():
     return __version__
 
-
 def current_dir():
     return os.path.abspath(os.path.dirname(__file__))
 
-
 def get_html_theme_path():
     """Return list of HTML theme paths."""
     return [current_dir()]
 
-
 def get_html_static_path():
     """Return list of HTML static paths."""
-    current_dir = current_dir()
-    return [
-        os.path.join(current_dir, "crate", "static"),
-    ]
-
+    return [os.path.join(current_dir(), "crate", "static")]
 
 def get_html_template_path():
     """Return list of HTML template paths."""
-    current_dir = current_dir()
-    return [
-        os.path.join(current_dir, "crate"),
-    ]
+    return [os.path.join(current_dir(), "crate")]
+
+
+def _add_crate_navigation(app, pagename, templatename, context, doctree):
+    """
+    Sphinx event handler: Add enhanced navigation to template context.
+
+    Generates multi-project navigation HTML and processes it through
+    Furo's navigation enhancer to add collapsible icons and checkboxes.
+    """
+
+    from furo.navigation import get_navigation_tree
+
+    navigation_html = generate_crate_navigation_html(context)
+
+    # Process through Furo's navigation enhancer
+    enhanced_navigation = get_navigation_tree(navigation_html)
+
+    # Add to context for use in templates
+    context["crate_navigation_tree"] = enhanced_navigation
+
+def setup(app):
+    """
+    Registers event handlers to setup navigation.
+    """
+    app.connect("html-page-context", _add_crate_navigation)
+    return {
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }
diff --git a/src/crate/theme/rtd/conf/__init__.py b/src/crate/theme/rtd/conf/__init__.py
@@ -33,6 +33,7 @@
 exclude_trees = ["pyenv", "tmp", "out", "parts", "clients", "eggs"]
 
 extensions = [
+    "crate.theme.rtd",  # CrateDB theme extension with Furo navigation integration
     "myst_nb",
     "sphinx_copybutton",
     "sphinx_design",
@@ -82,7 +83,8 @@
 }
 # https://sphinx-design.readthedocs.io/en/latest/badges_buttons.html#fontawesome-icons
 html_css_files = [
-    "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.1.1/css/all.min.css"
+    "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.1.1/css/all.min.css",
+    # Note: furo-collapsible-toc.scss is bundled via index.css import
 ]
 
 html_extra_path = ["_extra"]
diff --git a/src/crate/theme/rtd/crate/sidebar.html b/src/crate/theme/rtd/crate/sidebar.html
@@ -8,7 +8,7 @@
     {% endif %}
   </div>
   {% endif %}
-  <nav class="bs-docs-sidenav bs-sidenav nav" role="complementary">
+  <nav class="bs-docs-sidenav sidebar-tree bs-sidenav nav" role="complementary">
 
     {% if theme_navbar_links %}
       {%- for link in theme_navbar_links %}
diff --git a/src/crate/theme/rtd/crate/sidebartoc.html b/src/crate/theme/rtd/crate/sidebartoc.html
@@ -1,171 +1,2 @@
-<ul class="toctree nav nav-list">
-
-  {% if project == 'SQL 99' %}
-
-  <li class="current">
-    <a class="current-active" href="{{ pathto(master_doc) }}">SQL-99 Complete, Really</a>
-    {{ toctree(maxdepth=2|toint, collapse=False, includehidden=theme_globaltoc_includehidden|tobool) }}
-  </li>
-
-  {% else %}
-
-  <!-- Search. -->
-  <li>
-    <div class="search-link">
-      <div id="docsearch" style="min-height: 36px; margin-bottom: 20px;"></div>
-    </div>
-  </li>
-
-  <!-- Section A: -->
-  {% if project == 'CrateDB: Guide' %}
-    <!-- Show root index page in the Guide project selected if needed -->
-    {% if pagename == 'index' %}
-      <li class="current">
-        <a class="current-active" href="{{ pathto(master_doc) }}">Overview</a>
-      </li>
-    {% else %}
-      <li class="navleft-item"><a href="{{ pathto(master_doc) }}">Overview</a></li>
-    {% endif %}
-    <!-- Show all remaining TOC entries in the root -->
-    <li class="current toctree-l0">
-      {{ toctree(maxdepth=-1|toint, titles_only=True, collapse=True, includehidden=theme_globaltoc_includehidden|tobool) }}
-    </li>
-  {% else %}
-    <!-- Show Guide sections as links in other projects -->
-    <li class="navleft-item"><a href="/docs/guide/">Overview</a></li>
-    <li class="navleft-item"><a href="/docs/guide/start/">Getting Started</a></li>
-    <li class="navleft-item"><a href="/docs/guide/handbook/">Handbook</a></li>
-  {% endif %}
-
-  {% if project == 'CrateDB Cloud' %}
-    <li class="current">
-      <a class="current-active" href="{{ pathto(master_doc) }}">CrateDB Cloud</a>
-      {{ toctree(maxdepth=-1|toint, titles_only=True, collapse=True, includehidden=theme_globaltoc_includehidden|tobool) }}
-    </li>
-  {% else %}
-    <li class="navleft-item"><a href="/docs/cloud/">CrateDB Cloud</a></li>
-  {% endif %}
-
-  {% if project == 'CrateDB: Reference' %}
-    <li class="current">
-      <a class="current-active" href="{{ pathto(master_doc) }}">Reference Manual</a>
-      {{ toctree(maxdepth=-1|toint, titles_only=True, collapse=True, includehidden=theme_globaltoc_includehidden|tobool) }}
-    </li>
-  {% else %}
-    <li class="navleft-item"><a href="/docs/crate/reference/">Reference Manual</a></li>
-  {% endif %}
-
-  <!-- Section B. -->
-  {% if project == 'CrateDB: Admin UI' %}
-  <li class="current border-top">
-    <a class="current-active" href="{{ pathto(master_doc) }}">Admin UI</a>
-    {{ toctree(maxdepth=-1|toint, titles_only=True, collapse=True, includehidden=theme_globaltoc_includehidden|tobool) }}
-  </li>
-  {% else %}
-  <li class="navleft-item border-top"><a href="/docs/crate/admin-ui/">Admin UI</a></li>
-  {% endif %}
-
-  {% if project == 'CrateDB: Crash CLI' %}
-  <li class="current">
-    <a class="current-active" href="{{ pathto(master_doc) }}">CrateDB CLI</a>
-    {{ toctree(maxdepth=-1|toint, titles_only=True, collapse=False, includehidden=theme_globaltoc_includehidden|tobool) }}
-  </li>
-  {% else %}
-  <li class="navleft-item"><a href="/docs/crate/crash/">CrateDB CLI</a></li>
-  {% endif %}
-
-  {% if project == 'CrateDB Cloud: Croud CLI' %}
-  <li class="current">
-    <a class="current-active" href="{{ pathto(master_doc) }}">Cloud CLI</a>
-    {{ toctree(maxdepth=-1|toint, titles_only=True, collapse=False, includehidden=theme_globaltoc_includehidden|tobool) }}
-  </li>
-  {% else %}
-  <li class="navleft-item"><a href="/docs/cloud/cli/">Cloud CLI</a></li>
-  {% endif %}
-
-  <li class="navleft-item">
-    <a href="/docs/guide/connect/drivers.html">Database Drivers</a>
-  </li>
-  {%
-  set driver_projects = [
-    'CrateDB JDBC', 'CrateDB DBAL', 'CrateDB PDO', 'CrateDB Python', 'SQLAlchemy Dialect', 'CrateDB Npgsql'
-  ]
-  %}
-  {% if project in driver_projects or (project == 'CrateDB: Guide' and pagename.startswith('connect')) %}
-  <li>
-    <ul>
-      <!-- Section C. -->
-      {% if project == 'CrateDB JDBC' %}
-      <li class="current">
-        <a class="current-active" href="{{ pathto(master_doc) }}">JDBC</a>
-        {{ toctree(maxdepth=-1|toint, titles_only=True, collapse=False, includehidden=theme_globaltoc_includehidden|tobool) }}
-      </li>
-      {% else %}
-      <li class="navleft-item"><a href="/docs/jdbc/">JDBC</a></li>
-      {% endif %}
-      {% if project == 'CrateDB DBAL' %}
-      <li class="current">
-        <a class="current-active" href="{{ pathto(master_doc) }}">PHP DBAL</a>
-        {{ toctree(maxdepth=-1|toint, titles_only=True, collapse=False, includehidden=theme_globaltoc_includehidden|tobool) }}
-      </li>
-      {% else %}
-      <li class="navleft-item"><a href="/docs/dbal/">PHP DBAL</a></li>
-      {% endif %}
-      {% if project == 'CrateDB PDO' %}
-      <li class="current">
-        <a class="current-active" href="{{ pathto(master_doc) }}">PHP PDO</a>
-        {{ toctree(maxdepth=-1|toint, titles_only=True, collapse=False, includehidden=theme_globaltoc_includehidden|tobool) }}
-      </li>
-      {% else %}
-      <li class="navleft-item"><a href="/docs/pdo/">PHP PDO</a></li>
-      {% endif %}
-      {% if project == 'CrateDB Python' %}
-      <li class="current">
-        <a class="current-active" href="{{ pathto(master_doc) }}">Python</a>
-        {{ toctree(maxdepth=-1|toint, titles_only=True, collapse=False, includehidden=theme_globaltoc_includehidden|tobool) }}
-      </li>
-      {% else %}
-      <li class="navleft-item"><a href="/docs/python/">Python</a></li>
-      {% endif %}
-      {% if project == 'SQLAlchemy Dialect' %}
-      <li class="current">
-        <a class="current-active" href="{{ pathto(master_doc) }}">SQLAlchemy</a>
-        {{ toctree(maxdepth=-1|toint, titles_only=True, collapse=False, includehidden=theme_globaltoc_includehidden|tobool) }}
-      </li>
-      {% else %}
-      <li class="navleft-item"><a href="/docs/sqlalchemy-cratedb/">SQLAlchemy</a></li>
-      {% endif %}
-      {% if project == 'CrateDB Npgsql' %}
-      <li class="current">
-        <a class="current-active" href="{{ pathto(master_doc) }}">.NET Npgsql</a>
-        {{ toctree(maxdepth=-1|toint, titles_only=True, collapse=False, includehidden=theme_globaltoc_includehidden|tobool) }}
-      </li>
-      {% else %}
-      <li class="navleft-item"><a href="/docs/npgsql/">.NET Npgsql</a></li>
-      {% endif %}
-    </ul>
-  </li>
-  {% endif %}
-
-  <!-- Section D. -->
-  <li class="navleft-item border-top"><a target="_blank" href="/support/">Support</a></li>
-  <li class="navleft-item"><a target="_blank" href="https://community.cratedb.com/">Community</a></li>
-
-  <!-- Section E. -->
-  {% if project == 'CrateDB documentation theme' %}
-    <li class="current border-top">
-      <a class="current-active" href="{{ pathto(master_doc) }}">Documentation theme</a>
-      {{ toctree(maxdepth=-1|toint, titles_only=True, collapse=True, includehidden=theme_globaltoc_includehidden|tobool) }}
-    </li>
-  {% endif %}
-
-  {% if project == 'Doing Docs' %}
-  <li class="current">
-    <a class="current-active" href="{{ pathto(master_doc) }}">Doing Docs at CrateDB</a>
-    {{ toctree(maxdepth=-1|toint, titles_only=True, collapse=False, includehidden=theme_globaltoc_includehidden|tobool) }}
-  </li>
-  {% endif %}
-
-  {% endif %}
-
-</ul>
+{# Enhanced navigation generated by Sphinx extension using Furo's navigation enhancer #}
+{{ crate_navigation_tree }}
diff --git a/src/crate/theme/rtd/crate/static/css/crateio-rtd.css b/src/crate/theme/rtd/crate/static/css/crateio-rtd.css
diff --git a/src/crate/theme/rtd/crate/static/css/furo-collapsible-toc.scss b/src/crate/theme/rtd/crate/static/css/furo-collapsible-toc.scss
diff --git a/src/crate/theme/rtd/crate/static/css/index.css b/src/crate/theme/rtd/crate/static/css/index.css
diff --git a/src/crate/theme/rtd/crate/static/js/custom.js b/src/crate/theme/rtd/crate/static/js/custom.js
diff --git a/src/crate/theme/rtd/sidebartoc.py b/src/crate/theme/rtd/sidebartoc.py
