docs: group user and contributor guide nav into captioned sections

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>
 

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>
 ```

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
-```

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>