Re-add improved toc navigation with icons (#682)

bmunkholm · web-flow · commit f3a1722d333b · 2026-01-08T14:07:35.000+01:00
* TOC state is now persisted across page navigation and reloads, allowing multiple sections to remain expanded simultaneously. Changed sidebar TOC generation from HTML/Jinja templates to Python (``sidebartoc.py``) to enable Furo's navigation enhancements.
* CrateDB Npgsql docs were removed.
diff --git a/.gitignore b/.gitignore
@@ -21,3 +21,4 @@ dist
 eggs
 node_modules*
 yarn-error.log
+_*
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -5,6 +5,12 @@ CHANGES
 
 Unreleased
 ----------
+- Re-added TOC expand/collapse icons with improved navigation behavior: TOC
+  state is now persisted across page navigation and reloads, allowing multiple
+  sections to remain expanded simultaneously. Changed sidebar TOC generation
+  from HTML/Jinja templates to Python (``sidebartoc.py``) to enable Furo's
+  navigation enhancements. Originally introduced in 0.43.0, reverted in 0.44.0.
+- CrateDB Npgsql docs were removed.
 
 2025/12/19 0.45.0
 -----------------
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
@@ -32,27 +32,17 @@
 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")]
diff --git a/src/crate/theme/rtd/conf/__init__.py b/src/crate/theme/rtd/conf/__init__.py
@@ -82,7 +82,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"]
@@ -344,9 +345,12 @@ def apply_html_context_custom(app_inited):
     from crate.theme.rtd.crate.directives import stepper
     stepper.setup(app)
 
+    # Use icons for navigation using Furo
+    from crate.theme.rtd.sidebartoc import add_crate_navigation
+    app.connect("html-page-context", add_crate_navigation)
+
     return {
         "parallel_read_safe": True,
         "parallel_write_safe": True,
         "version": __version__,
     }
-
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
@@ -149,15 +149,6 @@ div.hero.danger {
   }
 }
 
-.bs-docs-sidenav .toctree ul ul ul {
-  display: none;
-}
-
-.bs-docs-sidenav .toctree li.current > ul,
-.bs-docs-sidenav .toctree ul li.active > ul {
-  display: block !important;
-}
-
 /* Remove indentation for toctree-l0 wrapper - used to display TOC entries at top level */
 .bs-docs-sidenav .toctree li.toctree-l0 > ul,
 .bs-docs-sidenav .toctree li.toctree-l0 > ul > li {
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
