Skip to content

Commit 407298f

Browse files
timsaucerclaude
timsaucer
and
claude
authored
Improve documentation site layout (#1578)
* docs: refresh theme — pydata-sphinx-theme 0.16, top navbar, dark mode 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) <noreply@anthropic.com> * docs: collapse navbar to section landing pages 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) <noreply@anthropic.com> * 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) <noreply@anthropic.com> * 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) <noreply@anthropic.com> * docs: render sidebar nav on landing page 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) <noreply@anthropic.com> * docs: render expandable chevrons in sidebar nav Switch the sidebar toctree call from toctree() to generate_toctree_html with collapse=False, so nested <ul>s render into the DOM for every branch. The pydata-sphinx-theme JS then wraps them in <details> 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) <noreply@anthropic.com> * 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) <noreply@anthropic.com> * docs: add Links sidebar section for external references 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) <noreply@anthropic.com> * docs: consolidate external URLs into a single Links nav item 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) <noreply@anthropic.com> * 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) <noreply@anthropic.com> * 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) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent bfa14f4 commit 407298f

12 files changed

Lines changed: 240 additions & 112 deletions

File tree

‎docs/source/_static/favicon.svg‎

Lines changed: 10 additions & 0 deletions
Loading

‎docs/source/_static/theme_overrides.css‎

Lines changed: 9 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -21,62 +21,34 @@
2121
/* Customizing with theme CSS variables */
2222

2323
:root {
24-
--pst-color-active-navigation: 215, 70, 51;
2524
--pst-color-link-hover: 215, 70, 51;
2625
--pst-color-headerlink: 215, 70, 51;
27-
/* Use normal text color (like h3, ..) instead of primary color */
28-
--pst-color-h1: var(--color-text-base);
29-
--pst-color-h2: var(--color-text-base);
30-
/* Use softer blue from bootstrap's default info color */
26+
/* Softer blue from bootstrap's default info color */
3127
--pst-color-info: 23, 162, 184;
32-
--pst-header-height: 0px;
3328
}
3429

3530
code {
3631
color: rgb(215, 70, 51);
3732
}
3833

39-
.footer {
40-
text-align: center;
41-
}
42-
43-
/* Ensure the logo is properly displayed */
44-
45-
.navbar-brand {
46-
height: auto;
47-
width: auto;
34+
html[data-theme="dark"] code {
35+
color: rgb(255, 138, 117);
4836
}
4937

50-
a.navbar-brand img {
51-
height: auto;
52-
width: auto;
53-
max-height: 15vh;
54-
max-width: 100%;
38+
.footer {
39+
text-align: center;
5540
}
5641

5742

58-
/* This is the bootstrap CSS style for "table-striped". Since the theme does
59-
not yet provide an easy way to configure this globally, it easier to simply
60-
include this snippet here than updating each table in all rst files to
61-
add ":class: table-striped" */
43+
/* Bootstrap "table-striped" applied globally so individual tables in
44+
user-guide pages don't need ":class: table-striped" added one by one. */
6245

6346
.table tbody tr:nth-of-type(odd) {
6447
background-color: rgba(0, 0, 0, 0.05);
6548
}
6649

67-
68-
/* Limit the max height of the sidebar navigation section. Because in our
69-
custimized template, there is more content above the navigation, i.e.
70-
larger logo: if we don't decrease the max-height, it will overlap with
71-
the footer.
72-
Details: min(15vh, 110px) for the logo size, 8rem for search box etc*/
73-
74-
@media (min-width:720px) {
75-
@supports (position:-webkit-sticky) or (position:sticky) {
76-
.bd-links {
77-
max-height: calc(100vh - min(15vh, 110px) - 8rem)
78-
}
79-
}
50+
html[data-theme="dark"] .table tbody tr:nth-of-type(odd) {
51+
background-color: rgba(255, 255, 255, 0.05);
8052
}
8153

8254

‎docs/source/_templates/docs-sidebar.html‎

Lines changed: 0 additions & 19 deletions
This file was deleted.

‎docs/source/_templates/layout.html‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,5 @@
11
{% extends "pydata_sphinx_theme/layout.html" %}
22

3-
{# Silence the navbar #}
4-
{% block docs_navbar %}
5-
{% endblock %}
6-
73
<!--
84
Custom footer
95
-->

‎docs/source/_templates/sidebar-globaltoc.html‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
{# Renders the global document toctree on every page (including the
2+
landing page) with pydata-sphinx-theme's collapsible chevrons.
3+
4+
The stock sidebar-nav-bs.html starts at the current section and is
5+
stripped from the sidebar list by suppress_sidebar_toctree() on the
6+
root page (no parent section). Using generate_toctree_html with
7+
startdepth=0 renders the whole tree from root with the bootstrap
8+
classes the theme's JS uses for expand/collapse toggles. Naming the
9+
template "sidebar-globaltoc" sidesteps the suppress filter, which
10+
matches on "sidebar-nav-bs.html" specifically. #}
11+
<nav class="bd-docs-nav bd-links" aria-label="{{ _('Section Navigation') }}">
12+
<p class="bd-links__title" role="heading" aria-level="1">{{ _("Section Navigation") }}</p>
13+
<div class="bd-toc-item navbar-nav">
14+
{# collapse=False so nested <ul>s render into the DOM for every
15+
branch; the theme's JS then adds the expand/collapse chevrons
16+
on top. show_nav_level is driven by theme_show_nav_level (set
17+
in conf.py) so callers can adjust how deep the sidebar opens
18+
by default without editing this template. #}
19+
{{- generate_toctree_html(
20+
"sidebar",
21+
startdepth=0,
22+
show_nav_level=theme_show_nav_level | int,
23+
maxdepth=theme_navigation_depth | int,
24+
collapse=False,
25+
includehidden=True,
26+
titles_only=True
27+
)
28+
-}}
29+
</div>
30+
</nav>

‎docs/source/conf.py‎

Lines changed: 34 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -35,8 +35,8 @@
3535

3636
# -- Project information -----------------------------------------------------
3737

38-
project = "Apache Arrow DataFusion"
39-
copyright = "2019-2024, Apache Software Foundation"
38+
project = "Apache DataFusion in Python"
39+
copyright = "2019-2026, Apache Software Foundation"
4040
author = "Apache Software Foundation"
4141

4242

@@ -115,30 +115,57 @@ def setup(sphinx) -> None:
115115
#
116116
html_theme = "pydata_sphinx_theme"
117117

118-
html_theme_options = {"use_edit_page_button": False, "show_toc_level": 2}
118+
html_theme_options = {
119+
"use_edit_page_button": False,
120+
"show_toc_level": 2,
121+
"logo": {
122+
"image_light": "_static/images/original.svg",
123+
"image_dark": "_static/images/original.svg",
124+
"alt_text": "Apache DataFusion in Python",
125+
},
126+
"navbar_start": ["navbar-logo"],
127+
"navbar_center": ["navbar-nav"],
128+
"navbar_end": ["navbar-icon-links", "theme-switcher"],
129+
"icon_links": [
130+
{
131+
"name": "GitHub",
132+
"url": "https://github.com/apache/datafusion-python",
133+
"icon": "fa-brands fa-github",
134+
},
135+
{
136+
"name": "Rust API docs (docs.rs)",
137+
"url": "https://docs.rs/datafusion/latest/datafusion/",
138+
"icon": "fa-brands fa-rust",
139+
},
140+
],
141+
"secondary_sidebar_items": [],
142+
"collapse_navigation": True,
143+
"show_nav_level": 2,
144+
}
119145

120146
html_context = {
121147
"github_user": "apache",
122-
"github_repo": "arrow-datafusion-python",
148+
"github_repo": "datafusion-python",
123149
"github_version": "main",
124150
"doc_path": "docs/source",
151+
"default_mode": "auto",
125152
}
126153

127154
# Add any paths that contain custom static files (such as style sheets) here,
128155
# relative to this directory. They are copied after the builtin static files,
129156
# so a file named "default.css" will overwrite the builtin "default.css".
130157
html_static_path = ["_static"]
131158

159+
html_favicon = "_static/favicon.svg"
160+
132161
# Copy agent-facing files (llms.txt) verbatim to the site root so they
133162
# resolve at conventional URLs like `https://.../python/llms.txt`.
134163
html_extra_path = ["llms.txt"]
135164

136-
html_logo = "_static/images/2x_bgwhite_original.png"
137-
138165
html_css_files = ["theme_overrides.css"]
139166

140167
html_sidebars = {
141-
"**": ["docs-sidebar.html"],
168+
"**": ["sidebar-globaltoc.html"],
142169
}
143170

144171
# tell myst_parser to auto-generate anchor links for headers h1, h2, h3

‎docs/source/contributor-guide/index.rst‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
.. Licensed to the Apache Software Foundation (ASF) under one
2+
.. or more contributor license agreements. See the NOTICE file
3+
.. distributed with this work for additional information
4+
.. regarding copyright ownership. The ASF licenses this file
5+
.. to you under the Apache License, Version 2.0 (the
6+
.. "License"); you may not use this file except in compliance
7+
.. with the License. You may obtain a copy of the License at
8+
9+
.. http://www.apache.org/licenses/LICENSE-2.0
10+
11+
.. Unless required by applicable law or agreed to in writing,
12+
.. software distributed under the License is distributed on an
13+
.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
.. KIND, either express or implied. See the License for the
15+
.. specific language governing permissions and limitations
16+
.. under the License.
17+
18+
=================
19+
Contributor Guide
20+
=================
21+
22+
Guides for contributors to the DataFusion in Python project.
23+
24+
.. toctree::
25+
:maxdepth: 2
26+
27+
introduction
28+
ffi

‎docs/source/index.rst‎

Lines changed: 4 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -52,47 +52,11 @@ Example
5252
df.show()
5353
5454
55-
.. _toc.links:
5655
.. toctree::
5756
:hidden:
5857
:maxdepth: 1
59-
:caption: LINKS
6058

61-
Github and Issue Tracker <https://github.com/apache/datafusion-python>
62-
Rust's API Docs <https://docs.rs/datafusion/latest/datafusion/>
63-
Code of conduct <https://github.com/apache/datafusion/blob/main/CODE_OF_CONDUCT.md>
64-
Examples <https://github.com/apache/datafusion-python/tree/main/examples>
65-
66-
.. _toc.guide:
67-
.. toctree::
68-
:hidden:
69-
:maxdepth: 1
70-
:caption: USER GUIDE
71-
72-
user-guide/introduction
73-
user-guide/basics
74-
user-guide/data-sources
75-
user-guide/dataframe/index
76-
user-guide/common-operations/index
77-
user-guide/io/index
78-
user-guide/configuration
79-
user-guide/distributing-work
80-
user-guide/sql
81-
user-guide/upgrade-guides
82-
user-guide/ai-coding-assistants
83-
84-
85-
.. _toc.contributor_guide:
86-
.. toctree::
87-
:hidden:
88-
:maxdepth: 1
89-
:caption: CONTRIBUTOR GUIDE
90-
91-
contributor-guide/introduction
92-
contributor-guide/ffi
93-
94-
.. _toc.api:
95-
.. toctree::
96-
:hidden:
97-
:maxdepth: 1
98-
:caption: API
59+
user-guide/index
60+
contributor-guide/index
61+
API Reference <autoapi/index>
62+
links

‎docs/source/links.rst‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
.. Licensed to the Apache Software Foundation (ASF) under one
2+
.. or more contributor license agreements. See the NOTICE file
3+
.. distributed with this work for additional information
4+
.. regarding copyright ownership. The ASF licenses this file
5+
.. to you under the Apache License, Version 2.0 (the
6+
.. "License"); you may not use this file except in compliance
7+
.. with the License. You may obtain a copy of the License at
8+
9+
.. http://www.apache.org/licenses/LICENSE-2.0
10+
11+
.. Unless required by applicable law or agreed to in writing,
12+
.. software distributed under the License is distributed on an
13+
.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
.. KIND, either express or implied. See the License for the
15+
.. specific language governing permissions and limitations
16+
.. under the License.
17+
18+
=====
19+
Links
20+
=====
21+
22+
External resources for the DataFusion in Python project.
23+
24+
.. toctree::
25+
:maxdepth: 1
26+
27+
GitHub and Issue Tracker <https://github.com/apache/datafusion-python>
28+
Rust API Docs <https://docs.rs/datafusion/latest/datafusion/>
29+
Code of Conduct <https://github.com/apache/datafusion/blob/main/CODE_OF_CONDUCT.md>
30+
Examples <https://github.com/apache/datafusion-python/tree/main/examples>

‎docs/source/user-guide/index.rst‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
.. Licensed to the Apache Software Foundation (ASF) under one
2+
.. or more contributor license agreements. See the NOTICE file
3+
.. distributed with this work for additional information
4+
.. regarding copyright ownership. The ASF licenses this file
5+
.. to you under the Apache License, Version 2.0 (the
6+
.. "License"); you may not use this file except in compliance
7+
.. with the License. You may obtain a copy of the License at
8+
9+
.. http://www.apache.org/licenses/LICENSE-2.0
10+
11+
.. Unless required by applicable law or agreed to in writing,
12+
.. software distributed under the License is distributed on an
13+
.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
.. KIND, either express or implied. See the License for the
15+
.. specific language governing permissions and limitations
16+
.. under the License.
17+
18+
==========
19+
User Guide
20+
==========
21+
22+
The user guide walks through installing DataFusion in Python, building queries
23+
with the DataFrame API or SQL, reading and writing data, and tuning execution.
24+
25+
.. toctree::
26+
:maxdepth: 2
27+
28+
introduction
29+
basics
30+
data-sources
31+
dataframe/index
32+
common-operations/index
33+
io/index
34+
configuration
35+
distributing-work
36+
sql
37+
upgrade-guides
38+
ai-coding-assistants

0 commit comments

Comments
 (0)