Switch documentation theme to immaterial (w/ support for dark mode)

docs/build

@@ -6,9 +6,15 @@ cd "${BASH_SOURCE%/*}"
 
 test -t 1 && OPTS='-it' || OPTS=''
 
-SPHINX_IMAGE=${SPHINX_IMAGE:-ghcr.io/trinodb/build/sphinx:114}
+SPHINX_IMAGE=${SPHINX_IMAGE:-ghcr.io/trinodb/build/sphinx:115}
 
-docker run --security-opt label:disable --rm $OPTS -e TRINO_VERSION -u $(id -u):$(id -g) -v "$PWD":/docs $SPHINX_IMAGE \
+# Ensure target is empty so that sitemap is always fully generated
+rm -Rf target
+
+# Ensure a writable cache directory
+mkdir -p target/.cache
+
+docker run --security-opt label:disable --rm $OPTS -e TRINO_VERSION -e XDG_CACHE_HOME=/docs/target/.cache -u $(id -u):$(id -g) -v "$PWD":/docs $SPHINX_IMAGE \
   sphinx-build -q -j auto -b html -W --keep-going -d target/doctrees src/main/sphinx target/html
 
 # Sort sitemap for reproducible builds

docs/src/main/sphinx/admin.md

@@ -40,8 +40,6 @@ with Trino for further analysis or reporting.
 The following event listeners are available:
 
 ```{toctree}
-:titlesonly: true
-
 admin/event-listeners-http
 admin/event-listeners-kafka
 admin/event-listeners-mysql

docs/src/main/sphinx/admin/properties.md

@@ -12,8 +12,6 @@ catalog configuration properties. For more information on catalog configuration
 properties, refer to the {doc}`connector documentation </connector/>`.
 
 ```{toctree}
-:titlesonly: true
-
 General <properties-general>
 Client protocol <properties-client-protocol>
 HTTP server <properties-http-server>

docs/src/main/sphinx/conf.py

@@ -81,14 +81,15 @@ def setup(app):
     'issue',
     'sphinx_copybutton',
     'redirects',
-    'sphinxcontrib.jquery'
+    'sphinxcontrib.jquery',
+    'sphinx_immaterial'
 ]
 
 redirects_file = 'redirects.txt'
 
 templates_path = ['templates']
 
-source_suffix = '.rst'
+source_suffix = '.md'
 
 master_doc = 'index'
 
@@ -122,7 +123,7 @@ def setup(app):
 
 # -- Options for HTML output ---------------------------------------------------
 
-html_theme = 'sphinx_material'
+html_theme = 'sphinx_immaterial'
 
 html_static_path = ['static']
 
@@ -141,17 +142,57 @@ def setup(app):
 }
 
 html_theme_options = {
-    'base_url': html_baseurl,
-    'globaltoc_depth': -1,
-    'theme_color': '2196f3',
-    'color_primary': '',  # set in CSS
-    'color_accent': '',   # set in CSS
+    'site_url': html_baseurl,
+    'toc_title': 'Contents',
+    'features': [
+        'content.action.edit',
+        'content.action.view',
+        'content.code.copy',
+        'content.tabs.link',
+        'content.tooltips'
+        'navigation.expand',
+        'navigation.footer',
+        'navigation.sections',
+        'navigation.top',
+        'navigation.tracking',
+        'search.share',
+        'search.suggest',
+        'toc.follow',
+    ],
+    'icon': {
+        'repo': 'fontawesome/brands/github-alt',
+        'edit': 'material/file-edit-outline',
+        'view': 'material/file-eye-outline'
+    },
+    'palette': [
+        {
+            'media': '(prefers-color-scheme)',
+            'scheme': 'default',
+            'toggle': {
+                'icon': 'material/brightness-auto',
+                'name': 'Switch to light mode',
+            }
+        },
+        {
+            'media': '(prefers-color-scheme: light)',
+            'scheme': 'default',
+            'toggle': {
+                'icon': 'material/weather-sunny',
+                'name': 'Switch to dark mode',
+            }
+        },
+        {
+            'media': '(prefers-color-scheme: dark)',
+            'scheme': 'slate',
+            'toggle': {
+                'icon': 'material/weather-night',
+                'name': 'Switch to system preference',
+            }
+        },
+    ],
     'repo_url': 'https://github.com/trinodb/trino',
     'repo_name': 'Trino',
-    'version_json': '../versions.json',
-    'nav_previous_text': 'Previous',
-    'nav_next_text': 'Next',
-    'search_placeholder_text': 'Search'
+    'edit_uri': 'blob/master/docs/src/main/sphinx'
 }
 
 html_css_files = [
@@ -161,3 +202,11 @@ def setup(app):
 suppress_warnings = [
     'config.cache'
 ]
+
+object_description_options = [
+    ("c:.*", dict(toc_icon_class=None, toc_icon_text=None)),
+    ("cpp:.*", dict(toc_icon_class=None, toc_icon_text=None)),
+    ("py:.*", dict(toc_icon_class=None, toc_icon_text=None)),
+    ("json:.*", dict(toc_icon_class=None, toc_icon_text=None)),
+    ("std:.*", dict(toc_icon_class=None, toc_icon_text=None))
+]

docs/src/main/sphinx/index.md

@@ -1,8 +1,6 @@
 # Trino documentation
 
 ```{toctree}
-:titlesonly: true
-
 overview
 installation
 client
@@ -22,7 +20,5 @@ appendix
 
 ```{toctree}
 :maxdepth: 1
-:titlesonly: true
-
 release
 ```

docs/src/main/sphinx/static/trino.css

@@ -12,10 +12,6 @@ html {
     scroll-behavior: smooth;
 }
 
-div.highlight {
-    background-color: #f5f5f5;
-}
-
 .md-header, .md-hero, .md-tabs {
     background-color: #0B1367;
 }
@@ -53,16 +49,13 @@ div.highlight {
     height: 48px;
 }
 
-.md-typeset h1 {
-    color: rgba(0, 0, 0, .80);
-}
-
 .sig-name, .sig-paren {
     font-weight: bold;
 }
 
 .md-typeset code {
     padding: 0 0.3em;
+    border-radius: 0.3rem;
 }
 
 pre.literal-block {
@@ -81,15 +74,6 @@ pre.literal-block {
     font-size: unset;
 }
 
-@media only screen and (min-width: 88.25em) {
-    .md-grid {
-        max-width: 75rem;
-    }
-
-    .md-sidebar--secondary {
-        margin-left: 75rem;
-    }
-}
 
 .copybtn:hover {
     cursor: copy;
@@ -105,3 +89,8 @@ button.copybtn {
     position: relative;
     top: -5.5rem;
 }
+
+.toctree-wrapper ul {
+    list-style-type: none;
+    padding-left: 0;
+}

docs/src/main/sphinx/udf.md

@@ -7,7 +7,6 @@ value, similar to [built-in functions](/functions).
 More details are available in the following sections:
 
 ```{toctree}
-:titlesonly: true
 :maxdepth: 1
 
 udf/introduction

docs/src/main/sphinx/udf/python.md

@@ -61,7 +61,6 @@ The same UDF can also be declared as [](udf-catalog).
 Refer to the [](/udf/python/examples) for more complex use cases and examples.
 
 ```{toctree}
-:titlesonly: true
 :hidden:
 
 /udf/python/examples

docs/src/main/sphinx/udf/sql.md

@@ -23,7 +23,6 @@ operators](/functions) and other UDFs:
 * [](/udf/sql/while)
 
 ```{toctree}
-:titlesonly: true
 :hidden:
 
 sql/examples
@@ -104,4 +103,4 @@ The following limitations apply to SQL UDFs.
 Specifically this means that UDFs can not use `SELECT` queries to retrieve
 data or any other queries to process data within the UDF. Instead queries can
 use UDFs to process data. UDFs only work on data provided as input values and
-only provide output data from the `RETURN` statement.
+only provide output data from the `RETURN` statement.