apache · timsaucer · Jun 5, 2026 · Jun 5, 2026 · Jun 5, 2026 · Jun 5, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -84,9 +84,9 @@ Every Python function must include a docstring with usage examples.
 When adding or updating an aggregate or window function, ensure the corresponding
 site documentation is kept in sync:
 
-- **Aggregations**: `docs/source/user-guide/common-operations/aggregations.rst` —
+- **Aggregations**: `docs/source/user-guide/common-operations/aggregations.md` —
   add new aggregate functions to the "Aggregate Functions" list and include usage
   examples if appropriate.
-- **Window functions**: `docs/source/user-guide/common-operations/windows.rst` —
+- **Window functions**: `docs/source/user-guide/common-operations/windows.md` —
   add new window functions to the "Available Functions" list and include usage
   examples if appropriate.
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"
 
 
@@ -53,6 +53,10 @@
     "autoapi.extension",
 ]
 
+# NOTE: .rst stays alongside .md because sphinx-autoapi generates RST
+# under autoapi/ and Sphinx needs the suffix to parse it. The human-
+# authored docs are all MyST .md now; the .rst entry is only for the
+# autoapi build artifacts.
 source_suffix = {
     ".rst": "restructuredtext",
     ".md": "markdown",
@@ -115,34 +119,65 @@ 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
 myst_heading_anchors = 3
 
-# enable nice rendering of checkboxes for the task lists
-myst_enable_extensions = ["tasklist"]
+# MyST extensions:
+# - tasklist: GitHub-style `- [x]` checkboxes
+# - colon_fence: `:::{directive}` blocks (needed by execution-metrics.md
+#   after the RST -> MyST conversion)
+# - deflist: definition lists (used in a couple of converted pages)
+myst_enable_extensions = ["tasklist", "colon_fence", "deflist"]