Update docs theme to sphinx-immaterial

presto-docs/requirements.txt

@@ -1,3 +1,3 @@
 sphinx==7.2.6
-sphinx-material==0.0.35
-sphinx-copybutton==0.5.0
+sphinx-immaterial==0.11.11
+sphinx-copybutton==0.5.2

presto-docs/src/main/sphinx/_templates/partials/toc.html

@@ -0,0 +1,60 @@
+{#-
+This file was automatically generated - do not edit
+-#}
+{% set title = lang.t("toc.title") %}
+{% if config.mdx_configs.toc and config.mdx_configs.toc.title %}
+{% set title = config.mdx_configs.toc.title %}
+{% endif %}
+<nav class="md-nav md-nav--secondary">
+    <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
+        <li class="md-nav__item">
+            <a href="{{ page.edit_url }}" class="">
+                <span class="md-source__icon md-icon">
+                    {% include ".icons/material/eye.svg" %}
+                </span>
+                View Page Source
+            </a>
+        </li>
+        <li class="md-nav__item">
+            <a href="{{theme_repo_url}}/edit/master/presto-docs/src/main/sphinx/{{pagename}}.rst" class="">
+                <span class="md-source__icon md-icon">
+                    {% include ".icons/material/file-edit.svg" %}
+                </span>
+                Edit this page
+            </a>
+        </li>
+        <li class="md-nav__item">
+            <a href="https://github.com/prestodb/presto/issues/new?title=Documentation&labels=docs"
+                class="">
+                <span class="md-source__icon md-icon">
+                    {% include ".icons/fontawesome/solid/list.svg" %}
+                </span>
+                Create docs issue
+            </a>
+        </li>
+        <li class="md-nav__item">
+            <a href="https://github.com/prestodb/presto/issues/new" class="">
+                <span class="md-source__icon  md-icon">
+                    {% include ".icons/fontawesome/solid/list.svg" %}
+                </span>
+                Create project issue
+            </a>
+        </li>
+    </ul>
+    <hr>
+    {% set toc = page.toc %}
+    {% if use_integrated_local_toc %}
+    {% set toc = page.integrated_local_toc %}
+    {% endif %}
+    {% if toc %}
+    <label class="md-nav__title" for="__toc">
+        <span class="md-nav__icon md-icon"></span>
+        {{ title }}
+    </label>
+    <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
+        {% for toc_item in toc %}
+        {% include "partials/toc-item.html" %}
+        {% endfor %}
+    </ul>
+    {% endif %}
+</nav>

presto-docs/src/main/sphinx/conf.py

@@ -60,15 +60,16 @@ def get_version():
 
 # -- General configuration -----------------------------------------------------
 
-needs_sphinx = '3.3.0'
+
+needs_sphinx = '7.2.6'
 
 extensions = [
-    'sphinx_copybutton', 'download', 'issue', 'pr'
+    'sphinx_immaterial', 'sphinx_copybutton', 'download', 'issue', 'pr'
 ]
 
 copyright = 'The Presto Foundation. All rights reserved. Presto is a registered trademark of LF Projects, LLC'
 
-templates_path = ['templates']
+templates_path = ['_templates']
 
 source_suffix = '.rst'
 
@@ -96,7 +97,7 @@ def get_version():
 
 # -- Options for HTML output ---------------------------------------------------
 
-html_theme = 'sphinx_material'
+html_theme = 'sphinx_immaterial'
 
 # Set link name generated in the top bar.
 html_title = '%s %s Documentation' % (project, release)
@@ -107,101 +108,63 @@ def get_version():
 # html_baseurl = 'overview.html'
 
 html_static_path = ['static']
-html_css_files = [
-    'presto.css',
-]
 
 templates_path = ['_templates']
 
+# Set the primary domain to js because if left as the default python
+# the theme errors when functions aren't available in a python module
+primary_domain = 'js'
+
 html_add_permalinks = '#'
 html_show_copyright = True
 html_show_sphinx = False
 
-html_sidebars = {
-    "**": ['logo-text.html', 'globaltoc.html', 'localtoc.html', 'searchbox.html']
-}
-
-html_show_sourcelink = False
 
-# Material theme options (see theme.conf for more information)
 html_theme_options = {
 
-# Set the name to appear in the left sidebar/header. If not provided, uses
-# html_short_title if defined, or html_title
-  #  'nav_title': 'Project Name',
-
     # Set your GA account ID to enable tracking
-   'google_analytics_account': 'G-K7GB6F0LBZ',
-
-    # Specify a base_url used to generate sitemap.xml. If not
-    # specified, then no sitemap will be built.
-   'base_url': '/',
-
-# Colors
-# The theme color for mobile browsers. Hex color.
-    'theme_color': '374665',
- # Primary colors:
-# red, pink, purple, deep-purple, indigo, blue, light-blue, cyan,
-# teal, green, light-green, lime, yellow, amber, orange, deep-orange,
-# brown, grey, blue-grey, white. default is blue.
-    'color_primary': 'grey',
-    # Accent colors:
-# red, pink, purple, deep-purple, indigo, blue, light-blue, cyan,
-# teal, green, light-green, lime, yellow, amber, orange, deep-orange
-    'color_accent': 'blue',
-
-# Repository integration
-# Set the repo url for the link to appear
+    "analytics": {
+        "provider": "google",
+        "property": "G-K7GB6F0LBZ"
+    },
+    'features': [
+        'toc.follow',
+        'toc.sticky',
+    ],
+    'palette': [
+        {
+            "media": "(prefers-color-scheme: light)",
+            "scheme": "default",
+            "primary": "black",
+            "accent": "cyan",
+            "toggle": {
+                "icon": "material/toggle-switch-off-outline",
+                "name": "Switch to dark mode",
+            }
+        },
+        {
+            "media": "(prefers-color-scheme: dark)",
+            "scheme": "slate",
+            "primary": "light-blue",
+            "accent": "deep-orange",
+            "toggle": {
+                "icon": "material/toggle-switch",
+                "name": "Switch to light mode",
+            }
+        },
+    ],
+    'edit_uri': 'blob/master/presto-docs/src/main/sphinx',
+
+    # 'base_url': '/',
     'repo_url': 'https://github.com/prestodb/presto',
     'repo_name': 'Presto',
-    'repo_type': 'github',
-
-
-# TOC Tree generation
-# The maximum depth of the global TOC; set it to -1 to allow unlimited depth
-'globaltoc_depth': 2,
-# If true, TOC entries that are not ancestors of the current page are collapsed
-'globaltoc_collapse': True,
-# If true, the global TOC tree will also contain hidden entries
-'globaltoc_includehidden': False,
-
-
-# Include the master document at the top of the page in the breadcrumb bar.
-# You must also set this to true if you want to override the rootrellink block, in which
-# case the content of the overridden block will appear
-# master_doc = True
-
-# A list of dictionaries where each has three keys:
-#   href: The URL or pagename (str)
-#   title: The title to appear (str)
-#   internal: Flag indicating to use pathto (bool)
-# nav_links =
-
-# Text to appear at the top of the home page in a "hero" div. Must be a
-# dict[str, str] of the form pagename: hero text, e.g., {'index': 'text on index'}
-# heroes =
-
-# Enable the version dropdown feature. See the demo site for the structure
-# of the json file required.
-# 'version_dropdown': 'True',
-
-# Text to use in the dropdown menu
-# version_dropdown_text = Versions
-
-# Optional dictionary that to use when populating the version dropdown.
-# The key is the text that appears, and the value is the absolute path
-# of the alternative versions
-# version_info =
-
-# Relative path to json file. The default is "versions.json" which assumes the
-# file hosted in the root of the site. You can use other file names or locations, e.g.,
-# "_static/old_versions.json"
-# 'version_json': 'static/versions.json',
-
-# Table classes to _not_ strip.  Must be a list. Classes on this list are *not*
-# removed from tables. All other classes are removed, and only tables with outclasses
-# are styled by default.
-# table_classes =
-
 
+    # If true, TOC entries that are not ancestors of the current page are collapsed
+    'globaltoc_collapse': True,
+    "social": [
+        {
+            "icon": "fontawesome/brands/github",
+            "link": "https://github.com/prestodb/presto",
+        },
+    ],
 }