docs: Improve documentation layout (#2587)

Author: andygrove

docs/build.sh

@@ -31,7 +31,7 @@ rm -rf comet-0.10
 python3 generate-versions.py
 
 # Remove overview pages (this used to be part of the user guide but is now a top level page)
-rm temp/user-guide/0.9/overview.md
-rm temp/user-guide/0.8/overview.md
+rm temp/user-guide/0.9/overview.md 2> /dev/null
+rm temp/user-guide/0.8/overview.md 2> /dev/null
 
 make SOURCEDIR=`pwd`/temp html

docs/requirements.txt

@@ -15,9 +15,10 @@
 # specific language governing permissions and limitations
 # under the License.
 
-sphinx
+setuptools
+sphinx>=7.0,<8.0
 sphinx-reredirects
-pydata-sphinx-theme==0.8.0
-myst-parser
+pydata-sphinx-theme>=0.15.0,<0.16.0
+myst-parser>=2.0,<4.0
 maturin
 jinja2

docs/source/_static/theme_overrides.css

@@ -29,9 +29,36 @@
   --pst-color-h2: var(--color-text-base);
   /* Use softer blue from bootstrap's default info color */
   --pst-color-info: 23, 162, 184;
-  --pst-header-height: 0px;
+  --pst-content-max-width: 100%; /* center column */
+  --pst-font-size-base: 0.9rem;
 }
 
+/* --- remove the right (secondary) sidebar entirely --- */
+.bd-sidebar-secondary { display: none !important; }
+
+/* Some versions still reserve the grid column for it — collapse it */
+.bd-main {
+  /* left sidebar + content only */
+  grid-template-columns: 20rem minmax(0, 1fr) !important;
+}
+
+/* --- make the left (primary) sidebar small --- */
+.bd-sidebar-primary {
+  width: 20rem !important;
+  flex: 0 0 20rem !important;
+}
+
+/* Optional: make its text a bit tighter */
+.bd-sidebar-primary .bd-sidebar {
+  font-size: 0.9rem;
+}
+
+/* --- let the center content use all remaining width --- */
+.bd-content, .bd-article-container {
+  max-width: none !important;   /* remove internal cap */
+}
+
+
 code {
   color: rgb(215, 70, 51);
 }

docs/source/_templates/docs-sidebar.html

@@ -17,18 +17,9 @@
 under the License.
 -->
 
-<form class="bd-search d-flex align-items-center" action="{{ pathto('search') }}" method="get">
-  <i class="icon fas fa-search"></i>
-  <input type="search" class="form-control" name="q" id="search-input" placeholder="{{ theme_search_bar_text }}" aria-label="{{ theme_search_bar_text }}" autocomplete="off" >
-</form>
-
 <nav class="bd-links" id="bd-docs-nav" aria-label="Main navigation">
   <div class="bd-toc-item active">
-    {% if "python/api" in pagename or "python/generated" in pagename %}
-    {{ generate_nav_html("sidebar", startdepth=0, maxdepth=3, collapse=False, includehidden=True, titles_only=True) }}
-    {% else %}
-    {{ generate_nav_html("sidebar", startdepth=0, maxdepth=4, collapse=False, includehidden=True, titles_only=True) }}
-    {% endif %}
+    {{ toctree(maxdepth=4, collapse=True, includehidden=True, titles_only=True) }}
   </div>
 
   <a class="navbar-brand" href="{{ pathto(master_doc) }}">

docs/source/_templates/layout.html

@@ -19,10 +19,6 @@
 
 {% extends "pydata_sphinx_theme/layout.html" %}
 
-{# Silence the navbar #}
-{% block docs_navbar %}
-{% endblock %}
-
 <!--
     Custom footer
 -->

docs/source/conf.py

@@ -86,10 +86,24 @@
 html_theme = 'pydata_sphinx_theme'
 
 html_theme_options = {
-    "use_edit_page_button": True,
+    "use_edit_page_button": False,
+    "secondary_sidebar_items": [],
+    "collapse_navigation": True,
+    "navbar_start": [],
+    "navbar_center": ["navbar-nav"],
+    "navbar_end": ["navbar-icon-links", "theme-switcher"],
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/apache/datafusion-comet",
+            "icon": "fa-brands fa-github",
+        },
+    ],
+
 }
 
 html_context = {
+    "default_mode": "light",
     "github_user": "apache",
     "github_repo": "datafusion-comet",
     "github_version": "main",

docs/source/index.rst

@@ -49,10 +49,10 @@ as a native runtime to achieve improvement in terms of query efficiency and quer
    :caption: User Guides:
    :hidden:
 
-   Comet 0.12.0-SNAPSHOT <user-guide/latest/index>
-   Comet 0.10.x <user-guide/0.10/index>
-   Comet 0.9.x <user-guide/0.9/index>
-   Comet 0.8.x <user-guide/0.8/index>
+   0.12.0-SNAPSHOT <user-guide/latest/index>
+   0.10.x <user-guide/0.10/index>
+   0.9.x <user-guide/0.9/index>
+   0.8.x <user-guide/0.8/index>
 
 .. _toc.contributor-guide-links:
 .. toctree::