andygrove opened a new pull request, #4424:
URL: https://github.com/apache/datafusion-comet/pull/4424
## Which issue does this PR close?
Part of #4421. Lands step 1 of the migration plan (captions/grouping; no
page moves or content changes).
## Rationale for this change
The user guide and contributor guide toctrees had grown into flat 14- and
23-item lists with no narrative grouping. The issue proposes a section-based
layout that makes it obvious where Getting Started lives, what is reference vs.
operational vs. architectural, and where integrations and project mechanics
fit. Step 1 is the toctree restructure, kept small so reviewers see the new
shape without page renames or content rewrites.
The pydata-sphinx-theme used here builds the sidebar from the global TOC, so
nested toctree captions get flattened away. Without a sidebar fix the new
captions wouldn't render anywhere visible, so this PR also adjusts
`docs-sidebar.html` to render the per-section captions in the left nav.
## What changes are included in this PR?
`docs/source/user-guide/latest/index.rst` — split the single 14-item toctree
into 5 captioned toctrees:
- **Getting Started** — Installing Comet, Configuration Settings
- **What Comet Supports** — Supported Data Sources, Data Types, Operators,
Expressions, ScalaUDF and Java UDF Support, Compatibility Guide
- **Operating Comet** — Understanding Comet Plans, Tuning Guide, Metrics
Guide
- **Integrations** — Iceberg Guide, Kubernetes Guide
- **Advanced** — Building From Source
`docs/source/contributor-guide/index.md` — split the single 23-item toctree
into 7 captioned toctrees:
- **Getting Started** — Getting Started, Development Guide
- **Project Architecture** — Comet Plugin Overview, Arrow FFI, JVM Shuffle,
Native Shuffle, ANSI Error Propagation
- **Adding Functionality** — Adding a New Operator, Expression, Spark Version
- **Testing** — Comet SQL Tests, Spark SQL Tests, Iceberg Spark Tests
- **Debugging and Performance** — Debugging Guide, Benchmarking Guide,
Profiling, Tracing
- **Reference** — Supported Spark Expressions, Supported Spark Configurations
- **Project Mechanics** — Bug Triage, Release Process, Roadmap, GitHub and
Issue Tracker
No page renames, no file moves, no content rewrites in the page bodies. The
link labels in the toctree directives are unchanged from the originals.
`docs/source/_templates/docs-sidebar.html` — switch from the bare Sphinx
`toctree()` macro to pydata-sphinx-theme's `generate_toctree_html()` with a
section-relative `startdepth` so captions render in the sidebar:
- `user-guide/latest/*` starts at depth 2 (under `user-guide/index` →
`latest/index`)
- `contributor-guide/*` starts at depth 1 (under `contributor-guide/index`)
- Root, `search`, `genindex` and other orphan pages fall back to
`startdepth=0` (global TOC, same as before)
The fallback uses pydata's `suppress_sidebar_toctree(startdepth=...,
includehidden=True)` so pages without a captioned ancestor still render their
sidebar instead of erroring.
Out of scope for this PR (deferred from the issue):
- Moving Building From Source into the contributor guide
- New pages (Glossary, Architecture-in-5, FAQ, Version Support)
- Tighter "how to use this guide" intros on the two index pages
- Applying #4419 nomenclature
## How are these changes tested?
Built the docs with `sphinx-build -b html source build` and verified:
1. Build exits clean (0 new warnings — the 4 existing warnings about
`user-guide/0.{13,14,15,16}/index` are pre-existing and come from versions
generated by `generate-versions.py` at build time).
2. Each user-guide/latest page renders the 5 new captions in the sidebar in
order; each contributor-guide page renders the 7 new captions in order.
3. Prev/next ordering follows the new section order: e.g. `installation →
configs → datasources → … → kubernetes → source → Contributor Guide` and
`contributing → development → plugin_overview → … → release_process → roadmap`.
4. Root index, search, genindex, changelog, about, asf, and the
`user-guide/index` version selector still render correctly with their existing
captions.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
