From b79fe4b01657e02700809a9fc86cc133b317e77b Mon Sep 17 00:00:00 2001 From: Tim Saucer Date: Fri, 5 Jun 2026 08:46:17 -0400 Subject: [PATCH 01/11] =?UTF-8?q?docs:=20refresh=20theme=20=E2=80=94=20pyd?= =?UTF-8?q?ata-sphinx-theme=200.16,=20top=20navbar,=20dark=20mode?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bump pydata-sphinx-theme 0.8.0 -> 0.16 to enable the modern navbar slot API and dark/light theme switcher. Configure top navbar with logo, nav links, GitHub icon, and theme switcher in conf.py. Drop the custom docs-sidebar.html override and the layout.html block that silenced the navbar — both predate the slot API and conflict with the new theme. Strip CSS overrides that fought the old theme (--pst-header-height: 0, navbar-brand sizing) and add a dark-mode variant for the inline code color and table-stripe shading. Fix the stale github_repo ("arrow-datafusion-python" -> "datafusion-python") so future Edit-on- GitHub links resolve. Bump copyright year and project name. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/source/_static/theme_overrides.css | 46 ++++-------------- docs/source/_templates/docs-sidebar.html | 19 -------- docs/source/_templates/layout.html | 4 -- docs/source/conf.py | 36 +++++++++++---- pyproject.toml | 3 +- uv.lock | 59 ++++++++++++++++++++++-- 6 files changed, 92 insertions(+), 75 deletions(-) delete mode 100644 docs/source/_templates/docs-sidebar.html 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/conf.py b/docs/source/conf.py index b2e9bb8c3..a25ab01c6 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,35 @@ 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", + }, + ], + "secondary_sidebar_items": [], + "collapse_navigation": True, + "show_nav_level": 1, +} 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, @@ -133,14 +155,8 @@ def setup(sphinx) -> None: # 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"], -} - # tell myst_parser to auto-generate anchor links for headers h1, h2, h3 myst_heading_anchors = 3 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" From a4a7e611551d94d9dedcb6354df6ee6cbf4aa3f6 Mon Sep 17 00:00:00 2001 From: Tim Saucer Date: Fri, 5 Jun 2026 08:53:05 -0400 Subject: [PATCH 02/11] docs: collapse navbar to section landing pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Previous structure dumped every top-level toctree entry from index.rst into the navbar, producing eight items including external URLs ("Github and Issue Tracker", "Rust's API Docs", ...) that wrapped to two lines each. Introduce user-guide/index.rst and contributor-guide/index.rst as section landing pages with nested toctrees, then point index.rst at just those two plus autoapi/index. The navbar now reads "User Guide", "Contributor Guide", "API Reference" — three single-line entries. Move the external links into the index.rst body where they're discoverable without crowding navigation. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/source/contributor-guide/index.rst | 28 +++++++++++++++ docs/source/index.rst | 47 +++++-------------------- docs/source/user-guide/index.rst | 38 ++++++++++++++++++++ 3 files changed, 75 insertions(+), 38 deletions(-) create mode 100644 docs/source/contributor-guide/index.rst create mode 100644 docs/source/user-guide/index.rst 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..2114fa4b1 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -52,47 +52,18 @@ Example df.show() -.. _toc.links: -.. toctree:: - :hidden: - :maxdepth: 1 - :caption: LINKS +Further reading: - Github and Issue Tracker - Rust's API Docs - Code of conduct - Examples +* `Examples `_ — runnable scripts demonstrating common patterns. +* `GitHub repository and issue tracker `_. +* `Rust API docs `_ for the underlying engine. +* `Apache DataFusion code of conduct `_. -.. _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 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 From f4971a471864f0ee89a8b45226112006f28fa1ea Mon Sep 17 00:00:00 2001 From: Tim Saucer Date: Fri, 5 Jun 2026 08:59:52 -0400 Subject: [PATCH 03/11] docs: restore external links lost in navbar restructure Add Examples and Rust API as text links in the top navbar via the pydata-sphinx-theme external_links option. Nest the code-of-conduct link inside the Contributor Guide toctree so it appears alongside the other contributor pages. Drop the duplicate "Further reading" bullet list from the landing page now that every link has a permanent home. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/source/conf.py | 10 ++++++++++ docs/source/contributor-guide/index.rst | 1 + docs/source/index.rst | 8 -------- 3 files changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index a25ab01c6..bd3fa9fa1 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -133,6 +133,16 @@ def setup(sphinx) -> None: "icon": "fa-brands fa-github", }, ], + "external_links": [ + { + "name": "Examples", + "url": "https://github.com/apache/datafusion-python/tree/main/examples", + }, + { + "name": "Rust API", + "url": "https://docs.rs/datafusion/latest/datafusion/", + }, + ], "secondary_sidebar_items": [], "collapse_navigation": True, "show_nav_level": 1, diff --git a/docs/source/contributor-guide/index.rst b/docs/source/contributor-guide/index.rst index b32e08878..c304ba99c 100644 --- a/docs/source/contributor-guide/index.rst +++ b/docs/source/contributor-guide/index.rst @@ -26,3 +26,4 @@ Guides for contributors to the DataFusion in Python project. introduction ffi + Code of Conduct diff --git a/docs/source/index.rst b/docs/source/index.rst index 2114fa4b1..9bd1febb6 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -52,14 +52,6 @@ Example df.show() -Further reading: - -* `Examples `_ — runnable scripts demonstrating common patterns. -* `GitHub repository and issue tracker `_. -* `Rust API docs `_ for the underlying engine. -* `Apache DataFusion code of conduct `_. - - .. toctree:: :hidden: :maxdepth: 1 From 41030efe57679c2c3969a3fe9ad7bb351e0a8476 Mon Sep 17 00:00:00 2001 From: Tim Saucer Date: Fri, 5 Jun 2026 09:01:28 -0400 Subject: [PATCH 04/11] docs: render Rust API link as docs.rs icon next to GitHub Move the Rust API docs entry from external_links to icon_links and use the fa-brands fa-rust gear mark. Now sits next to the GitHub icon in navbar_end with matching visual weight instead of a wider text link. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/source/conf.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index bd3fa9fa1..c064ecc12 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -132,16 +132,17 @@ def setup(sphinx) -> None: "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", + }, ], "external_links": [ { "name": "Examples", "url": "https://github.com/apache/datafusion-python/tree/main/examples", }, - { - "name": "Rust API", - "url": "https://docs.rs/datafusion/latest/datafusion/", - }, ], "secondary_sidebar_items": [], "collapse_navigation": True, From 3c8b53072e94fbcd6c15168b587501aee45662fa Mon Sep 17 00:00:00 2001 From: Tim Saucer Date: Fri, 5 Jun 2026 09:07:27 -0400 Subject: [PATCH 05/11] docs: render sidebar nav on landing page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The default pydata-sphinx-theme sidebar-nav-bs starts at the current top-level section, so the root index — which has no parent section — ends up with an empty sidebar. The theme's layout also explicitly filters sidebar-nav-bs out of the sidebar list when suppress_sidebar_ toctree() returns true (which it does for root pages), so simply overriding sidebar-nav-bs.html in templates doesn't help. Add a sidebar-globaltoc.html template that calls Sphinx's toctree() global directly to render the full document tree, and wire it through html_sidebars under a name the theme's suppress filter doesn't strip. Landing page now shows User Guide / Contributor Guide / API Reference in the sidebar with the current section expanded on inner pages. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/source/_templates/sidebar-globaltoc.html | 15 +++++++++++++++ docs/source/conf.py | 4 ++++ 2 files changed, 19 insertions(+) create mode 100644 docs/source/_templates/sidebar-globaltoc.html diff --git a/docs/source/_templates/sidebar-globaltoc.html b/docs/source/_templates/sidebar-globaltoc.html new file mode 100644 index 000000000..4c6c2fccb --- /dev/null +++ b/docs/source/_templates/sidebar-globaltoc.html @@ -0,0 +1,15 @@ +{# Overrides pydata-sphinx-theme's sidebar-nav-bs to render the global + document toctree on every page (including the landing page). The + stock template's generate_toctree_html starts at the current + section, which leaves the root index with no sidebar at all. Using + the toctree() Jinja global instead always shows the top-level + structure, with the current section expanded and highlighted. #} + diff --git a/docs/source/conf.py b/docs/source/conf.py index c064ecc12..c28b331f0 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -168,6 +168,10 @@ def setup(sphinx) -> None: html_css_files = ["theme_overrides.css"] +html_sidebars = { + "**": ["sidebar-globaltoc"], +} + # tell myst_parser to auto-generate anchor links for headers h1, h2, h3 myst_heading_anchors = 3 From 52c0095332c9e71497776f75e8571c89bcbc9234 Mon Sep 17 00:00:00 2001 From: Tim Saucer Date: Fri, 5 Jun 2026 09:10:48 -0400 Subject: [PATCH 06/11] docs: render expandable chevrons in sidebar nav Switch the sidebar toctree call from toctree() to generate_toctree_html with collapse=False, so nested
    s render into the DOM for every branch. The pydata-sphinx-theme JS then wraps them in
    with fa-chevron-down toggles, matching the datafusion-comet sidebar where each section with children can be expanded inline. show_nav_level=1 keeps deeper levels collapsed on first load. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/source/_templates/sidebar-globaltoc.html | 34 +++++++++++++------ 1 file changed, 24 insertions(+), 10 deletions(-) diff --git a/docs/source/_templates/sidebar-globaltoc.html b/docs/source/_templates/sidebar-globaltoc.html index 4c6c2fccb..8656bcc23 100644 --- a/docs/source/_templates/sidebar-globaltoc.html +++ b/docs/source/_templates/sidebar-globaltoc.html @@ -1,15 +1,29 @@ -{# Overrides pydata-sphinx-theme's sidebar-nav-bs to render the global - document toctree on every page (including the landing page). The - stock template's generate_toctree_html starts at the current - section, which leaves the root index with no sidebar at all. Using - the toctree() Jinja global instead always shows the top-level - structure, with the current section expanded and highlighted. #} +{# 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. #} From f2ff3062f0faf69c755fbdb7425cbdc45b8fa1e5 Mon Sep 17 00:00:00 2001 From: Tim Saucer Date: Fri, 5 Jun 2026 09:24:32 -0400 Subject: [PATCH 07/11] docs: expand sidebar to show level 2 entries by default Bump show_nav_level 1 -> 2 so the landing-page sidebar opens with User Guide / Contributor Guide / API Reference already expanded to their immediate children. Deeper levels remain collapsed behind chevrons so the sidebar stays scannable. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index c28b331f0..7c8d21583 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -146,7 +146,7 @@ def setup(sphinx) -> None: ], "secondary_sidebar_items": [], "collapse_navigation": True, - "show_nav_level": 1, + "show_nav_level": 2, } html_context = { From 6c264870c67c2d709122ed10c58419018ce52f64 Mon Sep 17 00:00:00 2001 From: Tim Saucer Date: Fri, 5 Jun 2026 09:26:44 -0400 Subject: [PATCH 08/11] docs: add Links sidebar section for external references MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Restore the "Links" sidebar heading that the previous site had — GitHub and Issue Tracker, Rust API Docs, Code of Conduct, Examples. Implemented as a second hidden toctree with :caption: Links so the pydata-sphinx-theme sidebar renders the heading above the four external URLs. Drop Code of Conduct from the Contributor Guide toctree since it now lives under Links instead. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/source/contributor-guide/index.rst | 1 - docs/source/index.rst | 10 ++++++++++ 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/source/contributor-guide/index.rst b/docs/source/contributor-guide/index.rst index c304ba99c..b32e08878 100644 --- a/docs/source/contributor-guide/index.rst +++ b/docs/source/contributor-guide/index.rst @@ -26,4 +26,3 @@ Guides for contributors to the DataFusion in Python project. introduction ffi - Code of Conduct diff --git a/docs/source/index.rst b/docs/source/index.rst index 9bd1febb6..9f9e2b7bc 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -59,3 +59,13 @@ Example user-guide/index contributor-guide/index API Reference + +.. toctree:: + :hidden: + :maxdepth: 1 + :caption: Links + + GitHub and Issue Tracker + Rust API Docs + Code of Conduct + Examples From fd74a26588312621a2494f64ff9556f1a1d63862 Mon Sep 17 00:00:00 2001 From: Tim Saucer Date: Fri, 5 Jun 2026 09:28:22 -0400 Subject: [PATCH 09/11] docs: consolidate external URLs into a single Links nav item MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace the second hidden toctree (which expanded each external URL into its own navbar entry) with a dedicated links.rst landing page, and add a single "links" entry to the main toctree. Top navbar now shows User Guide / Contributor Guide / API Reference / Links — four items, no wrapping. Clicking Links opens the page that lists GitHub, Rust API Docs, Code of Conduct, and Examples. Drop the external_links Examples entry from conf.py since the same URL now lives on the Links page. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/source/conf.py | 6 ------ docs/source/index.rst | 11 +---------- docs/source/links.rst | 30 ++++++++++++++++++++++++++++++ 3 files changed, 31 insertions(+), 16 deletions(-) create mode 100644 docs/source/links.rst diff --git a/docs/source/conf.py b/docs/source/conf.py index 7c8d21583..919a27916 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -138,12 +138,6 @@ def setup(sphinx) -> None: "icon": "fa-brands fa-rust", }, ], - "external_links": [ - { - "name": "Examples", - "url": "https://github.com/apache/datafusion-python/tree/main/examples", - }, - ], "secondary_sidebar_items": [], "collapse_navigation": True, "show_nav_level": 2, diff --git a/docs/source/index.rst b/docs/source/index.rst index 9f9e2b7bc..6b72537da 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -59,13 +59,4 @@ Example user-guide/index contributor-guide/index API Reference - -.. toctree:: - :hidden: - :maxdepth: 1 - :caption: Links - - GitHub and Issue Tracker - Rust API Docs - Code of Conduct - Examples + 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 From 9e933fcbb4474b870985bd2301faf2e9d5d733fe Mon Sep 17 00:00:00 2001 From: Tim Saucer Date: Fri, 5 Jun 2026 09:32:41 -0400 Subject: [PATCH 10/11] docs: add favicon matching the main datafusion site Drop in the same favicon.svg the main datafusion.apache.org site uses (just the Apache DataFusion mark, no wordmark) and wire it through html_favicon. Browsers and bookmarks now show the project icon instead of the generic Sphinx page glyph. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/source/_static/favicon.svg | 10 ++++++++++ docs/source/conf.py | 2 ++ 2 files changed, 12 insertions(+) create mode 100644 docs/source/_static/favicon.svg 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/conf.py b/docs/source/conf.py index 919a27916..4cbc3ace8 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -156,6 +156,8 @@ 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"] From 99e10dee1826d13569d5c4a3d80a1781ab81ca7e Mon Sep 17 00:00:00 2001 From: Tim Saucer Date: Fri, 5 Jun 2026 09:56:39 -0400 Subject: [PATCH 11/11] docs: address Copilot review feedback on sidebar config Two small follow-ups from the Copilot reviewer on #1578: - Append .html to the html_sidebars entry. Sphinx's Jinja loader resolves both "sidebar-globaltoc" and "sidebar-globaltoc.html" to the same template, but the explicit form is closer to the spelling in the Sphinx docs and is harder to misread. - Update the inline comment in sidebar-globaltoc.html that still claimed show_nav_level=1 after we bumped it to 2 in conf.py. Now describes the variable wiring instead of hard-coding a number that has to be kept in sync with conf.py. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/source/_templates/sidebar-globaltoc.html | 5 +++-- docs/source/conf.py | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/source/_templates/sidebar-globaltoc.html b/docs/source/_templates/sidebar-globaltoc.html index 8656bcc23..f4aa2051f 100644 --- a/docs/source/_templates/sidebar-globaltoc.html +++ b/docs/source/_templates/sidebar-globaltoc.html @@ -13,8 +13,9 @@
    {# collapse=False so nested
      s render into the DOM for every branch; the theme's JS then adds the expand/collapse chevrons - on top. show_nav_level=1 keeps deeper levels collapsed by - default so the landing-page sidebar isn't a wall of links. #} + 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, diff --git a/docs/source/conf.py b/docs/source/conf.py index 4cbc3ace8..bb1473546 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -165,7 +165,7 @@ def setup(sphinx) -> None: html_css_files = ["theme_overrides.css"] html_sidebars = { - "**": ["sidebar-globaltoc"], + "**": ["sidebar-globaltoc.html"], } # tell myst_parser to auto-generate anchor links for headers h1, h2, h3