docs: comet docs design overhaul- phase 1 by pranamya123 · Pull Request #4353 · apache/datafusion-comet

pranamya123 · 2026-05-16T01:20:57Z

Key changes:

Design Overhaul of the Comet Docs website, changes in the current Phase 1 include

Added a dedicated homepage for Comet. The content in the homepage is borrowed from the existing comet overview page, open to suggestions/edits on it.
Section-scoped sidebar, sidebar now shows only the contents of the currently active top-nav section, eliminating the four-section list that duplicated the top nav. Falls back to all sections on the homepage.
each group toggles independently with aria-expanded state. Multiple groups can be open at once.
replaces the "submit → land on /search.html" flow with a live filter that hides non-matching nav items and highlights matching characters in place. Full-document search via the regular Sphinx search index still works.
Quiet, structured footer used across every page (was previously default pydata)
Used the accent color from the logo, across the site
Home tab added to the top navigation
Right-side page TOC re-enabled and auto-shown on pages with ≥3 H2s, hidden on short reference pages so it doesn't waste space (as shown in the screenshot below)
Trimmed the Breadcrumb from 5 segments down to 3 (dropped the home icon and the redundant "Comet User Guide" parent; verbose version label shortened from "Comet 0.16.0-SNAPSHOT User Guide" → "0.16.0-SNAPSHOT")
$COMET_VERSION substitution fix, moved into conf.py via a source-read hook so local Sphinx builds match production. Previously the literal placeholder leaked into page titles, breadcrumbs, and the toctree caption when building outside build.sh.
For Accessibility, every new interactive element has proper ARIA, custom orange focus rings (replacing the browser's pink/purple default), terminal cursor blink respects prefers-reduced-motion

In Phase 2, changes planned

content review across all pages
evaluate the presence of main header items, keep them only if they are relevant/important
add interactive/animated graphs to the home page

Files:
conf.py register comet-ux.js + page-toc + version hook
_templates/docs-sidebar.html cap toctree depth at 3 (no double-nesting)
_templates/layout.html structured project footer
_static/comet-ux.js all client-side enhancements (new file)
_static/theme_overrides.css visual theme + sidebar/footer/TOC styles

Which issue does this PR close?

Closes #.

Rationale for this change

What changes are included in this PR?

BEFORE

AFTER

With the right side page TOC

To test it out please visit this temporary site hosted on netlify - https://rainbow-cranachan-f70262.netlify.app/

How are these changes tested?

coderfender · 2026-05-16T02:03:19Z

Thank you @pranamya123 . Could you add further screenshots with before and after changes?

andygrove · 2026-05-16T02:42:47Z

+}
+
+
+# -- $COMET_VERSION substitution -------------------------------------------


This is very nice!

coderfender · 2026-05-16T19:20:15Z

I think the mobile layout has an issue @pranamya123

pranamya123 · 2026-05-16T22:14:21Z

I think the mobile layout has an issue @pranamya123

Thank you for this comment, I made the design responsive to all devices and redeployed, could you please check now in the same netlify link? @coderfender

coderfender · 2026-05-17T00:29:39Z

Thank you. It looks good now

coderfender · 2026-05-17T00:30:50Z

Seems like the Apache DataFusion Comet font is too less (even less than the description) here ? Can we probably highlight Apache DataFusion Comet better ?

nit : Would also be great to show the acceleration in the terminal
nit : Your existing Spark queries — now executed natively via DataFusion - probably could add comet here ?
Also on the user guide page:

(html_title)

Also, not sure if this is intended but I don't see older version docs :

current :

PR :

Missing some feature sections :

current :

PR :

…nd section scoping Visual + interaction overhaul of the published docs site, layered on top of pydata_sphinx_theme so the existing search index, theme switcher, and toctree generation all continue to work. Key changes: - Section-scoped sidebar: when a top-level tab is active, the sidebar shows only that section's contents. Eliminates the redundancy of repeating the top-nav items in the left rail. - Click-to-toggle expand/collapse arrows on every nav group (independent of page navigation). Uses real <button> elements + aria-expanded for accessibility. - In-sidebar live search filter with character-level highlighting. Replaces the redirect-to-/search.html flow for sidebar lookups; full-text search via Sphinx still works as before. - Right-side page TOC re-enabled, auto-hidden on pages with fewer than 3 H2 anchors so it doesn't waste space on short reference pages. - Breadcrumb trim: hide the home icon (logo handles it) and the redundant section-index breadcrumb item; shorten the verbose "Comet X.Y.Z User Guide" version label to just "X.Y.Z". - Footer: structured 3-column footer (Documentation / Community / Apache) with the project logo, tagline, copyright, and trademark notice. - \$COMET_VERSION substitution moved into conf.py via a source-read hook so that local Sphinx builds match what build.sh produces; previously the literal "\$COMET_VERSION" leaked into page titles, breadcrumbs, and the toctree caption when building directly from source/. Files: conf.py register comet-ux.js + page-toc + version hook _templates/docs-sidebar.html cap toctree depth at 3 (no double-nesting) _templates/layout.html structured project footer _static/comet-ux.js all client-side enhancements (new file) _static/theme_overrides.css visual theme + sidebar/footer/TOC styles

… edited the footer to less content/noise,

- Promote Apache DataFusion Comet to the hero H1 (was a small eyebrow) - Mention Comet in the terminal install demo - Fix html_title leaking as visible text on the User Guide page - Restore Use Commodity Hardware section - Keep sidebar consistent across all User Guide pages so clicking a Dev Snapshot child does not reload the sidebar with a different tree - Fix admonition icon overlapping the title text Older version docs render correctly once merged; they require docs/build.sh to run generate-versions.py, which Netlify previews skip.

pranamya123 · 2026-05-26T21:20:11Z

Thanks @coderfender — addressed in 328f8b6:

"Apache DataFusion Comet" is now the hero H1 (was the small eyebrow)
Terminal demo now mentions Comet by name in the inline comment
html_title leak fixed; reverted to standard markdown H1
"Use Commodity Hardware" section restored with the verbatim source paragraph
Sidebar stays consistent across all User Guide pages — clicking a Dev Snapshot child no longer reloads the sidebar with a different tree
Re older version docs: the Netlify preview only shows Development Snapshot
because Netlify doesn't run docs/build.sh (which calls generate-versions.py
to clone the released-version docs from GitHub). In production, the Apache
build runs that step, so 0.16.x (current) and Older Versions populate
correctly when this PR merges. No source change needed for that.

pranamya123 · 2026-05-26T23:16:20Z

Hi @andygrove, this PR is now ready for review. You can test out the new UI in https://rainbow-cranachan-f70262.netlify.app/ . Please let me know your feedback. TIA!

coderfender · 2026-05-27T01:34:17Z

Seeing some inconsistencies with the terminal display :

Seeing different sidebars :

PR :

Main :

Also missing important config:

PR :

Main :

Seeing issues with the expression data as well :

Could we please confirm that the text / content is not missing ?

coderfender

Left comments on missing content

andygrove reviewed May 16, 2026

View reviewed changes

Comment thread docs/source/_templates/layout.html Outdated

andygrove reviewed May 16, 2026

View reviewed changes

pranamya123 force-pushed the docs/sidebar-redesign branch from 672858a to 6fc267a Compare May 16, 2026 12:48

pranamya123 changed the title ~~docs: redesign sidebar UX with collapsible groups, in-place search, and section scoping~~ docs: redesign comet docs page- v1 May 16, 2026

pranamya123 changed the title ~~docs: redesign comet docs page- v1~~ docs:comet docs design overhaul- v1 May 16, 2026

pranamya123 changed the title ~~docs:comet docs design overhaul- v1~~ docs:comet docs design overhaul- phase 1 May 16, 2026

coderfender added documentation Improvements or additions to documentation enhancement New feature or request labels May 16, 2026

coderfender changed the title ~~docs:comet docs design overhaul- phase 1~~ docs: comet docs design overhaul- phase 1 May 16, 2026

pranamya123 force-pushed the docs/sidebar-redesign branch from 110a232 to e85fa47 Compare May 22, 2026 20:52

pranamya123 added 2 commits May 26, 2026 13:43

designed a new home page for comet, added Home section in the header,…

f4c1163

… edited the footer to less content/noise,

pranamya123 force-pushed the docs/sidebar-redesign branch from e85fa47 to 9926d3b Compare May 26, 2026 21:17

pranamya123 force-pushed the docs/sidebar-redesign branch from 9926d3b to 328f8b6 Compare May 26, 2026 21:18

pranamya123 marked this pull request as ready for review May 26, 2026 23:14

coderfender requested changes May 27, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: comet docs design overhaul- phase 1#4353

docs: comet docs design overhaul- phase 1#4353
pranamya123 wants to merge 3 commits into
apache:mainfrom
pranamya123:docs/sidebar-redesign

pranamya123 commented May 16, 2026 •

edited

Loading

Uh oh!

coderfender commented May 16, 2026

Uh oh!

Uh oh!

andygrove May 16, 2026

Uh oh!

coderfender commented May 16, 2026

Uh oh!

pranamya123 commented May 16, 2026

Uh oh!

coderfender commented May 17, 2026

Uh oh!

coderfender commented May 17, 2026 •

edited

Loading

Uh oh!

pranamya123 commented May 26, 2026

Uh oh!

pranamya123 commented May 26, 2026

Uh oh!

coderfender commented May 27, 2026 •

edited

Loading

Uh oh!

coderfender left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		}


		# -- $COMET_VERSION substitution -------------------------------------------

Conversation

pranamya123 commented May 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Which issue does this PR close?

Rationale for this change

What changes are included in this PR?

How are these changes tested?

Uh oh!

coderfender commented May 16, 2026

Uh oh!

Uh oh!

andygrove May 16, 2026

Choose a reason for hiding this comment

Uh oh!

coderfender commented May 16, 2026

Uh oh!

pranamya123 commented May 16, 2026

Uh oh!

coderfender commented May 17, 2026

Uh oh!

coderfender commented May 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pranamya123 commented May 26, 2026

Uh oh!

pranamya123 commented May 26, 2026

Uh oh!

coderfender commented May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderfender left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

pranamya123 commented May 16, 2026 •

edited

Loading

coderfender commented May 17, 2026 •

edited

Loading

coderfender commented May 27, 2026 •

edited

Loading