Improve integration with sphinx-immaterial theme

- Sets minimum version to sphinx-immaterial 0.13.2, which contains fixes
  for a number of issues I identified.

- Enables Python signature formatting with black.

- Replaces numpydoc with sphinx.ext.napoleon, since numpydoc is not
  compatible with sphinx-immaterial.

- Adds announcement.

- Configures sphinx-immaterial theme features.

- Adds zarr.dev link to TOC (easiest way to include it for now)

- Adds twitter/github/zulip links in footer.

- Fixes custom.css to work with attributes and css variables used by
  sphinx-immaterial.

Author: jbms

docs/_static/custom.css

@@ -1,14 +1,3 @@
-@import url('https://fonts.googleapis.com/css2?family=Lato:ital,wght@0,400;0,700;0,900;1,400;1,700;1,900&family=Open+Sans:ital,wght@0,400;0,600;1,400;1,600&display=swap');
-
-body {
-  font-family: 'Open Sans', sans-serif;
-}
-
-pre, code {
-  font-size: 100%;
-  line-height: 155%;
-}
-
 /* Style the active version button.
 
 - dev: orange
@@ -66,8 +55,8 @@ Nat Methods 8, 441 (2011). https://doi.org/10.1038/nmeth.1618
 
 .sd-card .sd-card-header {
   border: none;
-  background-color: white;
-  font-size: var(--pst-font-size-h5);
+  background-color: var(--md-default-bg-color);
+  font-size: 1.5rem;
   font-weight: bold;
   padding: 2.5rem 0rem 0.5rem 0rem;
 }
@@ -84,27 +73,19 @@ Nat Methods 8, 441 (2011). https://doi.org/10.1038/nmeth.1618
 }
 
 /* Dark theme tweaking */
-html[data-theme=dark] .sd-card img[src*='.svg'] {
+body[data-md-color-scheme=slate] .sd-card img[src*='.svg'] {
     filter: invert(0.82) brightness(0.8) contrast(1.2);
 }
 
 /* Main index page overview cards */
-html[data-theme=dark] .sd-card {
-  background-color:var(--pst-color-background);
+body[data-md-color-scheme=slate] .sd-card {
+  background-color:var(--md-default-bg-color);
 }
 
-html[data-theme=dark] .sd-shadow-sm {
+body[data-md-color-scheme=slate] .sd-shadow-sm {
     box-shadow: 0 .1rem 1rem rgba(250, 250, 250, .6) !important
 }
 
-html[data-theme=dark] .sd-card .sd-card-header {
-  background-color:var(--pst-color-background);
-}
-
-html[data-theme=dark] .sd-card .sd-card-footer {
-  background-color:var(--pst-color-background);
-}
-
-html[data-theme=dark] h1 {
-  color: var(--pst-color-primary);
+body[data-md-color-scheme=slate] .sd-card .sd-card-footer {
+  background-color:var(--md-default-bg-color);
 }

docs/_templates/base.html

@@ -0,0 +1,6 @@
+{% extends "!base.html" %}
+{% block announce %}
+  <p>
+    Zarr-Python 3 is here! Check out the release announcement <a href='https://zarr.dev/blog/zarr-python-3-release/'>here.</a>
+  </p>
+{% endblock %}

docs/conf.py

@@ -1,5 +1,3 @@
-#!/usr/bin/env python3
-#
 # zarr documentation build configuration file, created by
 # sphinx-quickstart on Mon May  2 21:40:09 2016.
 #
@@ -40,13 +38,13 @@
     "sphinx.ext.autosummary",
     "sphinx.ext.viewcode",
     "sphinx.ext.intersphinx",
-    'autoapi.extension',
-    "numpydoc",
+    "autoapi.extension",
+    "sphinx.ext.napoleon",
     "sphinx_issues",
-    "sphinx_copybutton",
     "sphinx_design",
     "sphinx_immaterial",
-    'sphinx_reredirects',
+    "sphinx_immaterial.apidoc.format_signatures",
+    "sphinx_reredirects",
 ]
 
 issues_github_path = "zarr-developers/zarr-python"
@@ -167,8 +165,24 @@ def skip_submodules(
 # further.  For a list of options available for each theme, see the
 # documentation.
 html_theme_options = {
-    # "github_url": "https://github.com/zarr-developers/zarr-python",
-    # "twitter_url": "https://twitter.com/zarr_dev",
+    "repo_url": "https://github.com/zarr-developers/zarr-python",
+    "social": [
+        {
+            "icon": "fontawesome/brands/twitter",
+            "link": "https://twitter.com/zarr_dev",
+            "name": "@zarr_dev on Twitter",
+        },
+        {
+            "icon": "simple/zulip",
+            "link": "https://ossci.zulipchat.com/",
+            "name": "Developer chat",
+        },
+        {
+            "icon": "fontawesome/brands/github",
+            "link": "https://github.com/zarr-developers/zarr-python/",
+            "name": "Source repository",
+        },
+    ],
     # "icon_links": [
     #     {
     #         "name": "Zarr Dev",
@@ -179,7 +193,46 @@ def skip_submodules(
     # ],
     # "collapse_navigation": True,
     "navigation_with_keys": False,
-    # "announcement": "Zarr-Python 3 is here! Check out the release announcement <a href='https://zarr.dev/blog/zarr-python-3-release/'>here.</a>",
+    "features": [
+        "navigation.expand",
+        "navigation.tabs",
+        "navigation.tabs.sticky",
+        "navigation.top",
+        "toc.sticky",
+        "toc.follow",
+        "announce.dismiss",
+        "content.action.view",
+        "navigation.footer",
+    ],
+    "palette": [
+        {
+            "media": "(prefers-color-scheme)",
+            "toggle": {
+                "icon": "material/brightness-auto",
+                "name": "Switch to light mode",
+            },
+        },
+        {
+            "media": "(prefers-color-scheme: light)",
+            "scheme": "default",
+            "primary": "indigo",
+            "accent": "indigo",
+            "toggle": {
+                "icon": "material/lightbulb",
+                "name": "Switch to dark mode",
+            },
+        },
+        {
+            "media": "(prefers-color-scheme: dark)",
+            "scheme": "slate",
+            "primary": "black",
+            "accent": "blue",
+            "toggle": {
+                "icon": "material/lightbulb-outline",
+                "name": "Switch to system preference",
+            },
+        },
+    ],
 }
 
 # Add any paths that contain custom themes here, relative to this directory.
@@ -280,7 +333,10 @@ def setup(app: sphinx.application.Sphinx) -> None:
 # Output file base name for HTML help builder.
 htmlhelp_basename = "zarrdoc"
 
-maximum_signature_line_length = 80
+object_description_options = [
+    ("py:.*", dict(black_format_style={}, include_fields_in_toc=False)),
+    ("py:(parameter|typeParameter)", dict(include_in_toc=False)),
+]
 
 # -- Options for LaTeX output ---------------------------------------------
 

docs/index.rst

@@ -14,6 +14,7 @@ Zarr-Python
     release-notes
     developers/index
     about
+    zarr.dev <https://zarr.dev>
 
 **Version**: |version|
 

pyproject.toml

@@ -93,11 +93,8 @@ docs = [
     'sphinx-autoapi==3.4.0',
     'sphinx_design',
     'sphinx-issues',
-    'sphinx-copybutton',
     'sphinx-reredirects',
-    'pydata-sphinx-theme',
-    'sphinx_immaterial',
-    'numpydoc',
+    'sphinx_immaterial>=0.13.2[black]',
     # Changelog generation
     'towncrier',
     # Optional dependencies to run examples