From 2ac6c1cd91d22f59306fad5ea63323742c0d7eb5 Mon Sep 17 00:00:00 2001
From: Andy Grove <agrove@apache.org>
Date: Mon, 25 May 2026 08:57:07 -0600
Subject: [PATCH] docs: group user and contributor guide nav into captioned
 sections

Reorganize the latest user-guide and the contributor-guide toctrees
into captioned section groupings to replace the flat 14-item and
23-item lists.

User guide (docs/source/user-guide/latest/index.rst):
- Getting Started: Installing Comet, Configuration Settings
- What Comet Supports: data sources, types, operators, expressions,
  ScalaUDF/Java UDF support
- Compatibility: Compatibility Guide (and its sub-pages)
- Operating Comet: Understanding Comet Plans, Tuning Guide, Metrics
- Integrations: Iceberg, Kubernetes
- Advanced: Building From Source

Contributor guide (docs/source/contributor-guide/index.md):
- Getting Started: Getting Started, Development Guide
- Project Architecture: plugin overview, Arrow FFI, JVM/Native
  Shuffle, ANSI Error Propagation
- Adding Functionality: operator, expression, Spark version
- Testing: Comet SQL, Spark SQL, Iceberg Spark Tests
- Debugging and Performance: Debugging, Benchmarking, Profiling,
  Tracing
- Reference: Supported Spark Expressions and Configurations
- Project Mechanics: Bug Triage, Release Process, Roadmap, GitHub

The pydata-sphinx-theme used here flattens nested toctree captions
when the sidebar is built from the global TOC, so the per-section
captions only render if the sidebar starts from the section root.
Update docs-sidebar.html to call generate_toctree_html with a
section-relative startdepth (2 for user-guide/latest pages, 1 for
contributor-guide pages, 0 otherwise) so the new captions appear in
the left nav.

Page bodies, file paths, and toctree entries are otherwise
unchanged. Prev/next ordering follows the new section order.

Part of #4421.
---
 docs/source/_templates/docs-sidebar.html      | 13 +++-
 docs/source/contributor-guide/index.md        | 60 ++++++++++++++++---
 .../user-guide/latest/compatibility/index.md  | 12 ----
 docs/source/user-guide/latest/index.rst       | 44 ++++++++++++--
 4 files changed, 103 insertions(+), 26 deletions(-)

diff --git a/docs/source/_templates/docs-sidebar.html b/docs/source/_templates/docs-sidebar.html
index 26e859eadc..a20c715d20 100644
--- a/docs/source/_templates/docs-sidebar.html
+++ b/docs/source/_templates/docs-sidebar.html
@@ -17,9 +17,20 @@
 under the License.
 -->
 
+{# Start the sidebar from the deepest captioned section the page lives under:
+   - user-guide/latest/* lives under user-guide/index.md → user-guide/latest/index.rst, so start at depth 2
+   - contributor-guide/* lives under contributor-guide/index.md, so start at depth 1
+   - root and orphan pages (search, genindex) fall back to the global toctree (depth 0). #}
+{% if pagename.startswith("user-guide/latest/") and not suppress_sidebar_toctree(startdepth=2, includehidden=True) %}
+  {% set sidebar_startdepth = 2 %}
+{% elif not suppress_sidebar_toctree(startdepth=1, includehidden=True) %}
+  {% set sidebar_startdepth = 1 %}
+{% else %}
+  {% set sidebar_startdepth = 0 %}
+{% endif %}
 <nav class="bd-links" id="bd-docs-nav" aria-label="Main navigation">
   <div class="bd-toc-item active">
-    {{ toctree(maxdepth=4, collapse=True, includehidden=True, titles_only=True) }}
+    {{ generate_toctree_html("sidebar", startdepth=sidebar_startdepth, maxdepth=4, collapse=False, includehidden=True, titles_only=True) }}
   </div>
 </nav>
 
diff --git a/docs/source/contributor-guide/index.md b/docs/source/contributor-guide/index.md
index f3bbfba044..c601dab87d 100644
--- a/docs/source/contributor-guide/index.md
+++ b/docs/source/contributor-guide/index.md
@@ -32,30 +32,72 @@ menu to read more.
 
 ```{toctree}
 :maxdepth: 2
-:caption: Contributor Guide
+:caption: Getting Started
 :hidden:
 
 Getting Started <contributing>
+Development Guide <development>
+```
+
+```{toctree}
+:maxdepth: 2
+:caption: Project Architecture
+:hidden:
+
 Comet Plugin Overview <plugin_overview>
 Arrow FFI <ffi>
 JVM Shuffle <jvm_shuffle>
 Native Shuffle <native_shuffle>
-Development Guide <development>
-Debugging Guide <debugging>
 ANSI Error Propagation <sql_error_propagation>
-Benchmarking Guide <benchmarking>
+```
+
+```{toctree}
+:maxdepth: 2
+:caption: Adding Functionality
+:hidden:
+
 Adding a New Operator <adding_a_new_operator>
 Adding a New Expression <adding_a_new_expression>
 Adding a New Spark Version <adding_a_new_spark_version>
-Supported Spark Expressions <spark_expressions_support>
-Supported Spark Configurations <spark_configs_support>
-Tracing <tracing>
-Profiling <profiling>
+```
+
+```{toctree}
+:maxdepth: 2
+:caption: Testing
+:hidden:
+
 Comet SQL Tests <sql-file-tests.md>
 Spark SQL Tests <spark-sql-tests.md>
 Iceberg Spark Tests <iceberg-spark-tests.md>
+```
+
+```{toctree}
+:maxdepth: 2
+:caption: Debugging and Performance
+:hidden:
+
+Debugging Guide <debugging>
+Benchmarking Guide <benchmarking>
+Profiling <profiling>
+Tracing <tracing>
+```
+
+```{toctree}
+:maxdepth: 2
+:caption: Reference
+:hidden:
+
+Supported Spark Expressions <spark_expressions_support>
+Supported Spark Configurations <spark_configs_support>
+```
+
+```{toctree}
+:maxdepth: 2
+:caption: Project Mechanics
+:hidden:
+
 Bug Triage <bug_triage>
-Roadmap <roadmap.md>
 Release Process <release_process>
+Roadmap <roadmap.md>
 Github and Issue Tracker <https://github.com/apache/datafusion-comet>
 ```
diff --git a/docs/source/user-guide/latest/compatibility/index.md b/docs/source/user-guide/latest/compatibility/index.md
index 59c6a906f1..542d6902ec 100644
--- a/docs/source/user-guide/latest/compatibility/index.md
+++ b/docs/source/user-guide/latest/compatibility/index.md
@@ -29,15 +29,3 @@ This guide documents areas where Comet's behavior is known to differ from Spark.
 - **Operators**: operator-level compatibility notes, including window functions and round-robin partitioning.
 - **Expressions**: per-expression compatibility notes, including cast.
 - **Spark versions**: version-specific known issues and limitations.
-
-```{toctree}
-:maxdepth: 1
-:hidden:
-
-scans
-floating-point
-regex
-operators
-expressions/index
-spark-versions
-```
diff --git a/docs/source/user-guide/latest/index.rst b/docs/source/user-guide/latest/index.rst
index 9587b2ee03..236f284ce0 100644
--- a/docs/source/user-guide/latest/index.rst
+++ b/docs/source/user-guide/latest/index.rst
@@ -34,20 +34,56 @@ to read more.
 .. _toc.user-guide-links-$COMET_VERSION:
 .. toctree::
    :maxdepth: 1
-   :caption: Comet $COMET_VERSION User Guide
+   :caption: Getting Started
    :hidden:
 
    Installing Comet <installation>
-   Building From Source <source>
+   Configuration Settings <configs>
+
+.. toctree::
+   :maxdepth: 1
+   :caption: What Comet Supports
+   :hidden:
+
    Supported Data Sources <datasources>
    Supported Data Types <datatypes>
    Supported Operators <operators>
    Supported Expressions <expressions>
    ScalaUDF and Java UDF Support <scala_java_udfs>
-   Configuration Settings <configs>
-   Compatibility Guide <compatibility/index>
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Compatibility
+   :hidden:
+
+   Overview <compatibility/index>
+   compatibility/scans
+   compatibility/floating-point
+   compatibility/regex
+   compatibility/operators
+   compatibility/expressions/index
+   compatibility/spark-versions
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Operating Comet
+   :hidden:
+
    Understanding Comet Plans <understanding-comet-plans>
    Tuning Guide <tuning>
    Metrics Guide <metrics>
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Integrations
+   :hidden:
+
    Iceberg Guide <iceberg>
    Kubernetes Guide <kubernetes>
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Advanced
+   :hidden:
+
+   Building From Source <source>