apache · timsaucer · Jun 5, 2026 · Jun 5, 2026 · Jun 5, 2026 · Jun 5, 2026
diff --git a/docs/source/_static/favicon.svg b/docs/source/_static/favicon.svg
diff --git a/docs/source/_static/theme_overrides.css b/docs/source/_static/theme_overrides.css
@@ -21,62 +21,34 @@
 /* Customizing with theme CSS variables */
 
 :root {
-  --pst-color-active-navigation: 215, 70, 51;
   --pst-color-link-hover: 215, 70, 51;
   --pst-color-headerlink: 215, 70, 51;
-  /* Use normal text color (like h3, ..) instead of primary color */
-  --pst-color-h1: var(--color-text-base);
-  --pst-color-h2: var(--color-text-base);
-  /* Use softer blue from bootstrap's default info color */
+  /* Softer blue from bootstrap's default info color */
   --pst-color-info: 23, 162, 184;
-  --pst-header-height: 0px;
 }
 
 code {
   color: rgb(215, 70, 51);
 }
 
-.footer {
-  text-align: center;
-}
-
-/* Ensure the logo is properly displayed */
-
-.navbar-brand {
-  height: auto;
-  width: auto;
+html[data-theme="dark"] code {
+  color: rgb(255, 138, 117);
 }
 
-a.navbar-brand img {
-  height: auto;
-  width: auto;
-  max-height: 15vh;
-  max-width: 100%;
+.footer {
+  text-align: center;
 }
 
 
-/* This is the bootstrap CSS style for "table-striped". Since the theme does
-not yet provide an easy way to configure this globally, it easier to simply
-include this snippet here than updating each table in all rst files to
-add ":class: table-striped" */
+/* Bootstrap "table-striped" applied globally so individual tables in
+   user-guide pages don't need ":class: table-striped" added one by one. */
 
 .table tbody tr:nth-of-type(odd) {
   background-color: rgba(0, 0, 0, 0.05);
 }
 
-
-/* Limit the max height of the sidebar navigation section. Because in our
-custimized template, there is more content above the navigation, i.e.
-larger logo: if we don't decrease the max-height, it will overlap with
-the footer.
-Details: min(15vh, 110px) for the logo size, 8rem for search box etc*/
-
-@media (min-width:720px) {
-  @supports (position:-webkit-sticky) or (position:sticky) {
-    .bd-links {
-      max-height: calc(100vh - min(15vh, 110px) - 8rem)
-    }
-  }
+html[data-theme="dark"] .table tbody tr:nth-of-type(odd) {
+  background-color: rgba(255, 255, 255, 0.05);
 }
 
 

diff --git a/docs/source/_templates/docs-sidebar.html b/docs/source/_templates/docs-sidebar.html
diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html
@@ -1,9 +1,5 @@
 {% extends "pydata_sphinx_theme/layout.html" %}
 
-{# Silence the navbar #}
-{% block docs_navbar %}
-{% endblock %}
-
 <!--
     Custom footer
 -->

diff --git a/docs/source/_templates/sidebar-globaltoc.html b/docs/source/_templates/sidebar-globaltoc.html
@@ -0,0 +1,30 @@
+{# Renders the global document toctree on every page (including the
+   landing page) with pydata-sphinx-theme's collapsible chevrons.
+
+   The stock sidebar-nav-bs.html starts at the current section and is
+   stripped from the sidebar list by suppress_sidebar_toctree() on the
+   root page (no parent section). Using generate_toctree_html with
+   startdepth=0 renders the whole tree from root with the bootstrap
+   classes the theme's JS uses for expand/collapse toggles. Naming the
+   template "sidebar-globaltoc" sidesteps the suppress filter, which
+   matches on "sidebar-nav-bs.html" specifically. #}
+<nav class="bd-docs-nav bd-links" aria-label="{{ _('Section Navigation') }}">
+  <p class="bd-links__title" role="heading" aria-level="1">{{ _("Section Navigation") }}</p>
+  <div class="bd-toc-item navbar-nav">
+    {# collapse=False so nested <ul>s render into the DOM for every
+       branch; the theme's JS then adds the expand/collapse chevrons
+       on top. show_nav_level is driven by theme_show_nav_level (set
+       in conf.py) so callers can adjust how deep the sidebar opens
+       by default without editing this template. #}
+    {{- generate_toctree_html(
+      "sidebar",
+      startdepth=0,
+      show_nav_level=theme_show_nav_level | int,
+      maxdepth=theme_navigation_depth | int,
+      collapse=False,
+      includehidden=True,
+      titles_only=True
+      )
+    -}}
+  </div>
+</nav>
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -35,8 +35,8 @@
 
 # -- Project information -----------------------------------------------------
 
-project = "Apache Arrow DataFusion"
-copyright = "2019-2024, Apache Software Foundation"
+project = "Apache DataFusion in Python"
+copyright = "2019-2026, Apache Software Foundation"
 author = "Apache Software Foundation"
 
 
@@ -115,30 +115,57 @@ def setup(sphinx) -> None:
 #
 html_theme = "pydata_sphinx_theme"
 
-html_theme_options = {"use_edit_page_button": False, "show_toc_level": 2}
+html_theme_options = {
+    "use_edit_page_button": False,
+    "show_toc_level": 2,
+    "logo": {
+        "image_light": "_static/images/original.svg",
+        "image_dark": "_static/images/original.svg",
+        "alt_text": "Apache DataFusion in Python",
+    },
+    "navbar_start": ["navbar-logo"],
+    "navbar_center": ["navbar-nav"],
+    "navbar_end": ["navbar-icon-links", "theme-switcher"],
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/apache/datafusion-python",
+            "icon": "fa-brands fa-github",
+        },
+        {
+            "name": "Rust API docs (docs.rs)",
+            "url": "https://docs.rs/datafusion/latest/datafusion/",
+            "icon": "fa-brands fa-rust",
+        },
+    ],
+    "secondary_sidebar_items": [],
+    "collapse_navigation": True,
+    "show_nav_level": 2,
+}
 
 html_context = {
     "github_user": "apache",
-    "github_repo": "arrow-datafusion-python",
+    "github_repo": "datafusion-python",
     "github_version": "main",
     "doc_path": "docs/source",
+    "default_mode": "auto",
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
+html_favicon = "_static/favicon.svg"
+
 # Copy agent-facing files (llms.txt) verbatim to the site root so they
 # resolve at conventional URLs like `https://.../python/llms.txt`.
 html_extra_path = ["llms.txt"]
 
-html_logo = "_static/images/2x_bgwhite_original.png"
-
 html_css_files = ["theme_overrides.css"]
 
 html_sidebars = {
-    "**": ["docs-sidebar.html"],
+    "**": ["sidebar-globaltoc.html"],
 }
 
 # tell myst_parser to auto-generate anchor links for headers h1, h2, h3

diff --git a/docs/source/contributor-guide/index.rst b/docs/source/contributor-guide/index.rst
@@ -0,0 +1,28 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements.  See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership.  The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License.  You may obtain a copy of the License at
+
+..   http://www.apache.org/licenses/LICENSE-2.0
+
+.. Unless required by applicable law or agreed to in writing,
+.. software distributed under the License is distributed on an
+.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+.. KIND, either express or implied.  See the License for the
+.. specific language governing permissions and limitations
+.. under the License.
+
+=================
+Contributor Guide
+=================
+
+Guides for contributors to the DataFusion in Python project.
+
+.. toctree::
+   :maxdepth: 2
+
+   introduction
+   ffi
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -52,47 +52,11 @@ Example
     df.show()
 
 
-.. _toc.links:
 .. toctree::
    :hidden:
    :maxdepth: 1
-   :caption: LINKS
 
-   Github and Issue Tracker <https://github.com/apache/datafusion-python>
-   Rust's API Docs <https://docs.rs/datafusion/latest/datafusion/>
-   Code of conduct <https://github.com/apache/datafusion/blob/main/CODE_OF_CONDUCT.md>
-   Examples <https://github.com/apache/datafusion-python/tree/main/examples>
-
-.. _toc.guide:
-.. toctree::
-   :hidden:
-   :maxdepth: 1
-   :caption: USER GUIDE
-
-   user-guide/introduction
-   user-guide/basics
-   user-guide/data-sources
-   user-guide/dataframe/index
-   user-guide/common-operations/index
-   user-guide/io/index
-   user-guide/configuration
-   user-guide/distributing-work
-   user-guide/sql
-   user-guide/upgrade-guides
-   user-guide/ai-coding-assistants
-
-
-.. _toc.contributor_guide:
-.. toctree::
-   :hidden:
-   :maxdepth: 1
-   :caption: CONTRIBUTOR GUIDE
-
-   contributor-guide/introduction
-   contributor-guide/ffi
-
-.. _toc.api:
-.. toctree::
-   :hidden:
-   :maxdepth: 1
-   :caption: API
+   user-guide/index
+   contributor-guide/index
+   API Reference <autoapi/index>
+   links
diff --git a/docs/source/links.rst b/docs/source/links.rst
@@ -0,0 +1,30 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements.  See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership.  The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License.  You may obtain a copy of the License at
+
+..   http://www.apache.org/licenses/LICENSE-2.0
+
+.. Unless required by applicable law or agreed to in writing,
+.. software distributed under the License is distributed on an
+.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+.. KIND, either express or implied.  See the License for the
+.. specific language governing permissions and limitations
+.. under the License.
+
+=====
+Links
+=====
+
+External resources for the DataFusion in Python project.
+
+.. toctree::
+   :maxdepth: 1
+
+   GitHub and Issue Tracker <https://github.com/apache/datafusion-python>
+   Rust API Docs <https://docs.rs/datafusion/latest/datafusion/>
+   Code of Conduct <https://github.com/apache/datafusion/blob/main/CODE_OF_CONDUCT.md>
+   Examples <https://github.com/apache/datafusion-python/tree/main/examples>
diff --git a/docs/source/user-guide/index.rst b/docs/source/user-guide/index.rst
@@ -0,0 +1,38 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements.  See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership.  The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License.  You may obtain a copy of the License at
+
+..   http://www.apache.org/licenses/LICENSE-2.0
+
+.. Unless required by applicable law or agreed to in writing,
+.. software distributed under the License is distributed on an
+.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+.. KIND, either express or implied.  See the License for the
+.. specific language governing permissions and limitations
+.. under the License.
+
+==========
+User Guide
+==========
+
+The user guide walks through installing DataFusion in Python, building queries
+with the DataFrame API or SQL, reading and writing data, and tuning execution.
+
+.. toctree::
+   :maxdepth: 2
+
+   introduction
+   basics
+   data-sources
+   dataframe/index
+   common-operations/index
+   io/index
+   configuration
+   distributing-work
+   sql
+   upgrade-guides
+   ai-coding-assistants
diff --git a/pyproject.toml b/pyproject.toml
@@ -219,8 +219,9 @@ docs = [
   "myst-parser>=3.0.1",
   "pandas>=2.0.3",
   "pickleshare>=0.7.5",
-  "pydata-sphinx-theme==0.8.0",
+  "pydata-sphinx-theme>=0.16,<0.17",
   "setuptools>=75.3.0",
   "sphinx-autoapi>=3.4.0",
+  "sphinx-reredirects>=0.1.5",
   "sphinx>=7.1.2",
 ]