diff --git a/docs/source/_static/favicon.svg b/docs/source/_static/favicon.svg
new file mode 100644
index 000000000..bf174719b
--- /dev/null
+++ b/docs/source/_static/favicon.svg
@@ -0,0 +1,10 @@
+
diff --git a/docs/source/_static/theme_overrides.css b/docs/source/_static/theme_overrides.css
index aaa40fba2..661454b12 100644
--- 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
deleted file mode 100644
index 44deeed25..000000000
--- a/docs/source/_templates/docs-sidebar.html
+++ /dev/null
@@ -1,19 +0,0 @@
-
-
-  }})
-
-
-
-
-
diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html
index 9f7880049..d83d283c7 100644
--- 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 %}
-
diff --git a/docs/source/_templates/sidebar-globaltoc.html b/docs/source/_templates/sidebar-globaltoc.html
new file mode 100644
index 000000000..f4aa2051f
--- /dev/null
+++ 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. #}
+
diff --git a/docs/source/conf.py b/docs/source/conf.py
index b2e9bb8c3..bb1473546 100644
--- 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,13 +115,40 @@ 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,
@@ -129,16 +156,16 @@ def setup(sphinx) -> None:
# 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
new file mode 100644
index 000000000..b32e08878
--- /dev/null
+++ 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
index 7edb69807..6b72537da 100644
--- 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
- Rust's API Docs
- Code of conduct
- 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
+ links
diff --git a/docs/source/links.rst b/docs/source/links.rst
new file mode 100644
index 000000000..10473f31b
--- /dev/null
+++ 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
+ Rust API Docs
+ Code of Conduct
+ Examples
diff --git a/docs/source/user-guide/index.rst b/docs/source/user-guide/index.rst
new file mode 100644
index 000000000..2d6b94392
--- /dev/null
+++ 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
index 2b6a976db..e18c1d57c 100644
--- 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",
]
diff --git a/uv.lock b/uv.lock
index 6673b7fe2..89617aed0 100644
--- a/uv.lock
+++ b/uv.lock
@@ -8,6 +8,18 @@ resolution-markers = [
"python_full_version < '3.11'",
]
+[[package]]
+name = "accessible-pygments"
+version = "0.0.5"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pygments" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/bc/c1/bbac6a50d02774f91572938964c582fff4270eee73ab822a4aeea4d8b11b/accessible_pygments-0.0.5.tar.gz", hash = "sha256:40918d3e6a2b619ad424cb91e556bd3bd8865443d9f22f1dcdf79e33c8046872", size = 1377899, upload-time = "2024-05-10T11:23:10.216Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/8d/3f/95338030883d8c8b91223b4e21744b04d11b161a3ef117295d8241f50ab4/accessible_pygments-0.0.5-py3-none-any.whl", hash = "sha256:88ae3211e68a1d0b011504b2ffc1691feafce124b845bd072ab6f9f66f34d4b7", size = 1395903, upload-time = "2024-05-10T11:23:08.421Z" },
+]
+
[[package]]
name = "alabaster"
version = "1.0.0"
@@ -357,6 +369,8 @@ docs = [
{ name = "setuptools" },
{ name = "sphinx" },
{ name = "sphinx-autoapi" },
+ { name = "sphinx-reredirects", version = "0.1.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+ { name = "sphinx-reredirects", version = "1.1.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" },
]
release = [
{ name = "pygithub" },
@@ -393,10 +407,11 @@ docs = [
{ name = "myst-parser", specifier = ">=3.0.1" },
{ name = "pandas", specifier = ">=2.0.3" },
{ name = "pickleshare", specifier = ">=0.7.5" },
- { name = "pydata-sphinx-theme", specifier = "==0.8.0" },
+ { name = "pydata-sphinx-theme", specifier = ">=0.16,<0.17" },
{ name = "setuptools", specifier = ">=75.3.0" },
{ name = "sphinx", specifier = ">=7.1.2" },
{ name = "sphinx-autoapi", specifier = ">=3.4.0" },
+ { name = "sphinx-reredirects", specifier = ">=0.1.5" },
]
release = [{ name = "pygithub", specifier = "==2.5.0" }]
@@ -1142,16 +1157,20 @@ wheels = [
[[package]]
name = "pydata-sphinx-theme"
-version = "0.8.0"
+version = "0.16.1"
source = { registry = "https://pypi.org/simple" }
dependencies = [
+ { name = "accessible-pygments" },
+ { name = "babel" },
{ name = "beautifulsoup4" },
{ name = "docutils" },
+ { name = "pygments" },
{ name = "sphinx" },
+ { name = "typing-extensions" },
]
-sdist = { url = "https://files.pythonhosted.org/packages/fc/d6/3921de802cf1ee771f0e76c9068b52498aeb8eeec6b830ff931c81c7ecf3/pydata_sphinx_theme-0.8.0.tar.gz", hash = "sha256:9f72015d9c572ea92e3007ab221a8325767c426783b6b9941813e65fa988dc90", size = 1123746, upload-time = "2022-01-15T19:25:25.712Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/00/20/bb50f9de3a6de69e6abd6b087b52fa2418a0418b19597601605f855ad044/pydata_sphinx_theme-0.16.1.tar.gz", hash = "sha256:a08b7f0b7f70387219dc659bff0893a7554d5eb39b59d3b8ef37b8401b7642d7", size = 2412693, upload-time = "2024-12-17T10:53:39.537Z" }
wheels = [
- { url = "https://files.pythonhosted.org/packages/91/26/0694318d46c7d90ab602ae27b24431e939f1600f9a4c69d1e727ec57289f/pydata_sphinx_theme-0.8.0-py3-none-any.whl", hash = "sha256:fbcbb833a07d3ad8dd997dd40dc94da18d98b41c68123ab0182b58fe92271204", size = 3284997, upload-time = "2022-01-15T19:25:23.807Z" },
+ { url = "https://files.pythonhosted.org/packages/e2/0d/8ba33fa83a7dcde13eb3c1c2a0c1cc29950a048bfed6d9b0d8b6bd710b4c/pydata_sphinx_theme-0.16.1-py3-none-any.whl", hash = "sha256:225331e8ac4b32682c18fcac5a57a6f717c4e632cea5dd0e247b55155faeccde", size = 6723264, upload-time = "2024-12-17T10:53:35.645Z" },
]
[[package]]
@@ -1459,6 +1478,38 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/de/d6/f2acdc2567337fd5f5dc091a4e58d8a0fb14927b9779fc1e5ecee96d9824/sphinx_autoapi-3.4.0-py3-none-any.whl", hash = "sha256:4027fef2875a22c5f2a57107c71641d82f6166bf55beb407a47aaf3ef14e7b92", size = 34095, upload-time = "2024-11-30T01:09:17.272Z" },
]
+[[package]]
+name = "sphinx-reredirects"
+version = "0.1.6"
+source = { registry = "https://pypi.org/simple" }
+resolution-markers = [
+ "python_full_version < '3.11'",
+]
+dependencies = [
+ { name = "sphinx", marker = "python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/16/6b/bcca2785de4071f604a722444d4d7ba8a9d40de3c14ad52fce93e6d92694/sphinx_reredirects-0.1.6.tar.gz", hash = "sha256:c491cba545f67be9697508727818d8626626366245ae64456fe29f37e9bbea64", size = 7080, upload-time = "2025-03-22T10:52:30.271Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/ac/6f/0b3625be30a1a50f9e4c2cb2ec147b08f15ed0e9f8444efcf274b751300b/sphinx_reredirects-0.1.6-py3-none-any.whl", hash = "sha256:efd50c766fbc5bf40cd5148e10c00f2c00d143027de5c5e48beece93cc40eeea", size = 5675, upload-time = "2025-03-22T10:52:29.113Z" },
+]
+
+[[package]]
+name = "sphinx-reredirects"
+version = "1.1.0"
+source = { registry = "https://pypi.org/simple" }
+resolution-markers = [
+ "python_full_version >= '3.14'",
+ "python_full_version >= '3.12' and python_full_version < '3.14'",
+ "python_full_version == '3.11.*'",
+]
+dependencies = [
+ { name = "sphinx", marker = "python_full_version >= '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/1b/8d/0e39fe2740d7d71417edf9a6424aa80ca2c27c17fc21282cdc39f90d5a40/sphinx_reredirects-1.1.0.tar.gz", hash = "sha256:fb9b195335ab14b43f8273287d0c7eeb637ba6c56c66581c11b47202f6718b29", size = 614624, upload-time = "2025-12-22T08:28:02.792Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/51/81/b5dd07067f3daac6d23687ec737b2d593740671ebcd145830c8f92d381c5/sphinx_reredirects-1.1.0-py3-none-any.whl", hash = "sha256:4b5692273c72cd2d4d917f4c6f87d5919e4d6114a752d4be033f7f5f6310efd9", size = 6351, upload-time = "2025-12-22T08:27:59.724Z" },
+]
+
[[package]]
name = "sphinxcontrib-applehelp"
version = "2.0.0"