Re: [PR] Improve documentation site layout [datafusion-python]

["Copilot (via GitHub)" <gi...@apache.org>]

Copilot commented on code in PR #1578:
URL: https://github.com/apache/datafusion-python/pull/1578#discussion_r3363016394


##########
docs/source/conf.py:
##########
@@ -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"],
 }

Review Comment:
   `html_sidebars` entries are template filenames; Sphinx expects the actual template name (including `.html`). Using `"sidebar-globaltoc"` will not resolve to `_templates/sidebar-globaltoc.html` and can cause the sidebar to disappear at build time.



##########
docs/source/_templates/sidebar-globaltoc.html:
##########
@@ -0,0 +1,29 @@
+{# 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=1 keeps deeper levels collapsed by
+       default so the landing-page sidebar isn't a wall of links. #}

Review Comment:
   The inline comment says `show_nav_level=1`, but the template is wired to `theme_show_nav_level` (configured as `show_nav_level=2` in `conf.py`). This mismatch is confusing when adjusting navigation behavior.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org