timsaucer opened a new pull request, #1578:
URL: https://github.com/apache/datafusion-python/pull/1578
# Which issue does this PR close?
Closes #.
# Rationale for this change
Phase 1 of a broader documentation site refresh. The Sphinx setup currently
pins `pydata-sphinx-theme==0.8.0` (released Jan 2022), which predates the
modern navbar slot API, the built-in light/dark theme switcher, and dual-logo
support. The sibling `datafusion-comet` project recently completed a similar
refresh and the resulting site is a noticeable improvement in navigation,
polish, and dark-mode legibility. This PR is the smallest self-contained step
toward that look-and-feel — it only touches the theme, navbar, and a handful of
stale strings in `conf.py`. Content migration (RST → MD) and multi-version
publishing are deliberately scoped to follow-up PRs so this one stays
reviewable as a pure visual upgrade.
# What changes are included in this PR?
- Bump `pydata-sphinx-theme` from `==0.8.0` to `>=0.16,<0.17` in
`[dependency-groups] docs` (`pyproject.toml`, `uv.lock`).
- Add `sphinx-reredirects>=0.1.5` to the docs group — needed by the upcoming
RST→MD migration so URL paths can move without breaking inbound links.
- Configure the modern theme in `docs/source/conf.py`:
- `html_theme_options` now declares `navbar_start` / `navbar_center` /
`navbar_end` with the logo, nav links, GitHub icon, and the theme switcher.
- `secondary_sidebar_items = []` removes the right-hand TOC clutter.
- `logo = {"image_light", "image_dark"}` replaces the legacy single
`html_logo` (same SVG for both modes today — a dedicated dark variant is a
follow-up).
- `html_context.default_mode = "auto"` so the site respects the user's OS
preference on first visit.
- Fix `html_context.github_repo` — the repo was renamed
`arrow-datafusion-python` → `datafusion-python` long ago.
- Bump `copyright = "2019-2026, …"` and rename `project` to `Apache
DataFusion in Python` to match how the site is referenced upstream.
- Delete `docs/source/_templates/docs-sidebar.html` — the override was
written for the v0.8 sidebar (search box + nav glued together) and is
incompatible with the v0.16 slot model. Theme defaults now provide the same
content.
- Drop the `{% block docs_navbar %}{% endblock %}` block in
`_templates/layout.html` that silenced the top navbar. The Apache trademark
footer customization is preserved.
- Trim `_static/theme_overrides.css`:
- Remove `--pst-header-height: 0px` (was needed when the navbar was
silenced; would now collapse the top bar).
- Remove the `--pst-color-active-navigation`, `--pst-color-h1`,
`--pst-color-h2` overrides — defaults in 0.16 already render correctly, and the
old overrides break dark mode.
- Remove the bespoke `.navbar-brand` / `a.navbar-brand img` rules — the
theme now handles logo sizing through its own variables.
- Remove the `.bd-links` max-height clamp — that hack existed only because
the old custom sidebar template put the logo inside the sidebar; the new layout
puts it in the top navbar.
- Add dark-mode variants for the inline-code accent color and the
`table-striped` row shading so both render with adequate contrast.
# Are there any user-facing changes?
Yes — purely visual to the published documentation site. No API changes, no
behavioral changes to the `datafusion` package itself. Changes a reader will
notice:
- A top navigation bar with the project logo, the user-guide /
contributor-guide links, a GitHub icon, and a light/dark theme switcher.
- Dark mode now actually renders correctly (the old overrides assumed a
single light theme).
- The right-hand "On this page" TOC is suppressed so the main content area
is wider.
- The site is built using a newer Sphinx theme; published HTML will look
meaningfully different.
No `api change` label — public APIs are untouched.
## Follow-ups (out of scope for this PR)
- A dedicated dark-mode logo (currently the same SVG is served for both
modes; the icon reads fine but the embedded text uses `#1F2937` and could use
better contrast on dark backgrounds).
- RST → MD content migration (Phase 2).
- Multi-version doc publishing à la `datafusion-comet` (Phase 3).
- `asf-site` publishing workflow (Phase 4).
--
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]
