🔧 Add sphinx-immaterial to doc theme builds (#190)

Author: chrisjsewell

docs/_static/sphinx_immaterial.css

@@ -0,0 +1,30 @@
+body {
+    --sd-fontsize-dropdown: .64rem;
+    --sd-fontsize-dropdown-title: .64rem;
+    --sd-fontweight-dropdown-title: 700;
+}
+
+details.sd-dropdown {
+    padding-left: 0;
+    padding-right: 0;
+}
+
+summary.sd-summary-title::after {
+    display: none;
+    right: 0 !important;
+}
+
+summary.sd-summary-title::before {
+    display: none;
+    left: 0 !important;
+}
+
+summary.sd-summary-title {
+    width: 100% !important;
+    margin-left: 0;
+    padding: .5em 1em !important;
+}
+
+summary.sd-summary-title svg.sd-octicon {
+    max-width: none !important;
+}

docs/conf.py

@@ -55,6 +55,39 @@
     html_theme_options = {
         "logo_only": True,
     }
+if html_theme == "sphinx_immaterial":
+    extensions.append("sphinx_immaterial")
+    html_css_files = ["sphinx_immaterial.css"]
+    html_theme_options = {
+        "icon": {
+            "repo": "fontawesome/brands/github",
+        },
+        "site_url": "https://sphinx-design.readthedocs.io/",
+        "repo_url": "https://github.com/executablebooks/sphinx-design",
+        "repo_name": "Sphinx-Design",
+        "palette": [
+            {
+                "media": "(prefers-color-scheme: light)",
+                "scheme": "default",
+                "primary": "blue",
+                "accent": "light-blue",
+                "toggle": {
+                    "icon": "material/weather-night",
+                    "name": "Switch to dark mode",
+                },
+            },
+            {
+                "media": "(prefers-color-scheme: dark)",
+                "scheme": "slate",
+                "primary": "blue",
+                "accent": "yellow",
+                "toggle": {
+                    "icon": "material/weather-sunny",
+                    "name": "Switch to light mode",
+                },
+            },
+        ],
+    }
 
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 myst_enable_extensions = ["colon_fence", "deflist", "substitution", "html_image"]

pyproject.toml

@@ -48,6 +48,7 @@ theme-furo = ["furo~=2024.5.4"]
 theme-pydata = ["pydata-sphinx-theme~=0.15.2"]
 theme-rtd = ["sphinx-rtd-theme~=2.0"]
 theme-sbt = ["sphinx-book-theme~=1.1"]
+theme-im = ["sphinx-immaterial~=0.11.11"]
 
 [tool.flit.sdist]
 exclude = [

tox.ini

@@ -1,6 +1,5 @@
 # To use tox, see https://tox.readthedocs.io
-# Simply pip or conda install tox
-# If you use conda, you may also want to install tox-conda
+# (you may also want to install tox-uv)
 # then run `tox` or `tox -- {pytest args}`
 # run in parallel using `tox -p`
 [tox]
@@ -15,7 +14,7 @@ extras =
     testing
 commands = pytest {posargs}
 
-[testenv:docs-{alabaster,rtd,pydata,sbt,furo}]
+[testenv:docs-{alabaster,rtd,pydata,sbt,furo,im}]
 description =
     Run documentation build for this theme
 extras =
@@ -24,6 +23,7 @@ extras =
     pydata: theme_pydata
     sbt: theme_sbt
     furo: theme_furo
+    im: theme_im
 allowlist_externals = echo
 passenv =
     BUILDER
@@ -35,6 +35,7 @@ setenv =
     pydata: SPHINX_THEME = pydata_sphinx_theme
     sbt: SPHINX_THEME = sphinx_book_theme
     furo: SPHINX_THEME = furo
+    im: SPHINX_THEME = sphinx_immaterial
 commands_pre =
   python -c "import shutil; shutil.rmtree('docs/_build/{env:BUILDER:html}/{env:SPHINX_THEME:}', ignore_errors=True) if '{env:CLEAN:}' else None"
 commands =