From 68ec6bdb06cedc11d8ea0b75238de3a263f00968 Mon Sep 17 00:00:00 2001 From: Aniket Singh Rawat Date: Fri, 7 Mar 2025 23:04:51 +0530 Subject: [PATCH 1/4] try out new theme --- docs/conf.py | 3 ++- pyproject.toml | 1 + 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 048e77f51d..49cd6d252c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -47,6 +47,7 @@ "sphinx_issues", "sphinx_copybutton", "sphinx_design", + "sphinx_immaterial", ] numpydoc_show_class_members = False @@ -129,7 +130,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = "pydata_sphinx_theme" +html_theme = "sphinx_immaterial" html_favicon = "_static/logo1.png" diff --git a/pyproject.toml b/pyproject.toml index dacd45ec2c..2d1596a9f1 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -49,6 +49,7 @@ docs = [ 'sphinx-issues', 'sphinx-copybutton', 'pydata-sphinx-theme', + 'sphinx_immaterial', 'numpydoc', 'numcodecs[msgpack]', ] From 8b70e39481751ff8ed6deeafb0cabb793509b9a4 Mon Sep 17 00:00:00 2001 From: Aniket Singh Rawat Date: Fri, 7 Mar 2025 23:15:13 +0530 Subject: [PATCH 2/4] remove unsupported options --- docs/conf.py | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index b09753e280..a76975e476 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -167,19 +167,19 @@ 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", - "icon_links": [ - { - "name": "Zarr Dev", - "url": "https://zarr.dev/", - "icon": "_static/logo1.png", - "type": "local", - }, - ], - "collapse_navigation": True, + # "github_url": "https://github.com/zarr-developers/zarr-python", + # "twitter_url": "https://twitter.com/zarr_dev", + # "icon_links": [ + # { + # "name": "Zarr Dev", + # "url": "https://zarr.dev/", + # "icon": "_static/logo1.png", + # "type": "local", + # }, + # ], + # "collapse_navigation": True, "navigation_with_keys": False, - "announcement": "Zarr-Python 3 is here! Check out the release announcement here.", + # "announcement": "Zarr-Python 3 is here! Check out the release announcement here.", } # Add any paths that contain custom themes here, relative to this directory. From 13d1b4c56f6c414c71a4f68a6ce80971140f4e5f Mon Sep 17 00:00:00 2001 From: Jeremy Maitin-Shepard Date: Wed, 12 Mar 2025 11:05:54 -0700 Subject: [PATCH 3/4] 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. --- docs/_static/custom.css | 35 +++++------------- docs/_templates/base.html | 6 ++++ docs/conf.py | 76 +++++++++++++++++++++++++++++++++------ docs/index.rst | 1 + pyproject.toml | 5 +-- 5 files changed, 82 insertions(+), 41 deletions(-) create mode 100644 docs/_templates/base.html mode change 100644 => 100755 docs/conf.py diff --git a/docs/_static/custom.css b/docs/_static/custom.css index 1d32606f9a..0f8ae4ec35 100644 --- a/docs/_static/custom.css +++ b/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); } diff --git a/docs/_templates/base.html b/docs/_templates/base.html new file mode 100644 index 0000000000..6bc156f1c3 --- /dev/null +++ b/docs/_templates/base.html @@ -0,0 +1,6 @@ +{% extends "!base.html" %} +{% block announce %} +

+ Zarr-Python 3 is here! Check out the release announcement here. +

+{% endblock %} diff --git a/docs/conf.py b/docs/conf.py old mode 100644 new mode 100755 index a76975e476..c643b39004 --- a/docs/conf.py +++ b/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 here.", + "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 --------------------------------------------- diff --git a/docs/index.rst b/docs/index.rst index 83d427e290..0effe65a2f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,6 +14,7 @@ Zarr-Python release-notes developers/index about + zarr.dev **Version**: |version| diff --git a/pyproject.toml b/pyproject.toml index d99d020369..b9ad455534 100644 --- a/pyproject.toml +++ b/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 From d9739240f1b7affa2b7c3e242b2b7d9f73be057d Mon Sep 17 00:00:00 2001 From: Aniket Singh Rawat <31622972+dikwickley@users.noreply.github.com> Date: Thu, 13 Mar 2025 12:44:10 +0530 Subject: [PATCH 4/4] fix --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index b9ad455534..3bb448253c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -94,7 +94,7 @@ docs = [ 'sphinx_design', 'sphinx-issues', 'sphinx-reredirects', - 'sphinx_immaterial>=0.13.2[black]', + 'sphinx_immaterial[black]>=0.13.2', # Changelog generation 'towncrier', # Optional dependencies to run examples