Skip to content

docs: comet docs design overhaul- phase 1#4353

Draft
pranamya123 wants to merge 3 commits into
apache:mainfrom
pranamya123:docs/sidebar-redesign
Draft

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

Conversation

@pranamya123
Copy link
Copy Markdown
Contributor

@pranamya123 pranamya123 commented May 16, 2026 •
edited
Loading

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
Screenshot 2026-05-16 at 9 10 02 AM

AFTER
Screenshot 2026-05-16 at 9 10 25 AM

With the right side page TOC
Screenshot 2026-05-16 at 9 30 03 AM

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

How are these changes tested?

@pranamya123
docs: redesign sidebar UX with collapsible groups, in-place search, a…
d2d5c6e 
…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
@coderfender
Copy link
Copy Markdown
Contributor

coderfender commented May 16, 2026

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

andygrove
andygrove reviewed May 16, 2026
View reviewed changes
Comment thread docs/source/_templates/layout.html Outdated
andygrove
andygrove reviewed May 16, 2026
View reviewed changes
Comment thread docs/source/conf.py
}


# -- $COMET_VERSION substitution -------------------------------------------
Copy link
Copy Markdown
Member

@andygrove andygrove May 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is very nice!

@pranamya123 pranamya123 force-pushed the docs/sidebar-redesign branch from 672858a to 6fc267a Compare May 16, 2026 12:48
@pranamya123 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 pranamya123 changed the title docs: redesign comet docs page- v1 docs:comet docs design overhaul- v1 May 16, 2026
@pranamya123 pranamya123 changed the title docs:comet docs design overhaul- v1 docs:comet docs design overhaul- phase 1 May 16, 2026
@coderfender coderfender added documentation Improvements or additions to documentation enhancement New feature or request labels May 16, 2026
@coderfender coderfender changed the title docs:comet docs design overhaul- phase 1 docs: comet docs design overhaul- phase 1 May 16, 2026
@coderfender
Copy link
Copy Markdown
Contributor

coderfender commented May 16, 2026

I think the mobile layout has an issue @pranamya123
image

@pranamya123
Copy link
Copy Markdown
Contributor Author

pranamya123 commented May 16, 2026

I think the mobile layout has an issue @pranamya123 image

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
Copy link
Copy Markdown
Contributor

coderfender commented May 17, 2026

Thank you. It looks good now

@coderfender
Copy link
Copy Markdown
Contributor

coderfender commented May 17, 2026 •
edited
Loading

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

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:
image
(html_title)

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

current :
image

PR :

image

Missing some feature sections :

current :
image

PR :

image

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@andygrove andygrove andygrove left review comments

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@pranamya123 @coderfender @andygrove @mbutrovich