Sync tooling and docs with cookiecutter-scverse v0.7.0 (phase 2+3)

- Switch from optional-dependencies to dependency-groups (PEP 735)
- Add hatch environments (default, docs, hatch-test matrix)
- Add build.yaml CI workflow (uv build + twine check)
- Replace prettier with biome, add pyproject-fmt and pre-commit-hooks
- Switch docs from mathjax to KaTeX, add sphinx-tabs and opengraph
- Update .readthedocs.yaml to use hatch docs:build
- Rewrite contributing.md with hatch/uv/pip tabs, keep plot-testing guide
- Add [tool.cruft] skip list for future template syncs
- Keep pixi config, html_logo, full intersphinx mappings, nitpicky=False

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: timtreis

.github/workflows/build.yaml

@@ -0,0 +1,26 @@
+name: Check Build
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          filter: blob:none
+          fetch-depth: 0
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+      - name: Build package
+        run: uv build
+      - name: Check package
+        run: uvx twine check --strict dist/*.whl

.pre-commit-config.yaml

@@ -5,19 +5,36 @@ default_stages:
   - pre-commit
   - pre-push
 minimum_pre_commit_version: 2.16.0
-ci:
-  skip: []
 repos:
-  - repo: https://github.com/rbubley/mirrors-prettier
-    rev: v3.8.1
+  - repo: https://github.com/biomejs/pre-commit
+    rev: v2.3.10
     hooks:
-      - id: prettier
+      - id: biome-format
+        exclude: ^\.cruft\.json$ # inconsistent indentation with cruft
+  - repo: https://github.com/tox-dev/pyproject-fmt
+    rev: v2.11.1
+    hooks:
+      - id: pyproject-fmt
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.15.5
     hooks:
-      - id: ruff
+      - id: ruff-check
+        types_or: [python, pyi, jupyter]
         args: [--fix, --exit-non-zero-on-fix]
       - id: ruff-format
+        types_or: [python, pyi, jupyter]
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: detect-private-key
+      - id: check-ast
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+        args: [--fix=lf]
+      - id: trailing-whitespace
+      - id: check-case-conflict
+      - id: check-merge-conflict
+        args: [--assume-in-merge]
   - repo: https://github.com/pre-commit/mirrors-mypy
     rev: v1.19.1
     hooks:

.readthedocs.yaml

@@ -1,15 +1,16 @@
+# https://docs.readthedocs.io/en/stable/config-file/v2.html
 version: 2
 build:
   os: ubuntu-24.04
   tools:
-    python: "3.12"
-  commands:
-    - asdf plugin add uv
-    - asdf install uv latest
-    - asdf global uv latest
-    - uv venv
-    - uv pip install .[docs,pre]
-    - .venv/bin/python -m sphinx -T -b html -d docs/_build/doctrees -D language=en docs $READTHEDOCS_OUTPUT/html
-sphinx:
-  configuration: docs/conf.py
-  fail_on_warning: false
+    python: "3.13"
+    nodejs: latest
+  jobs:
+    create_environment:
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
+    build:
+      html:
+        - uvx hatch run docs:build
+        - mv docs/_build $READTHEDOCS_OUTPUT

.vscode/extensions.json

@@ -13,6 +13,6 @@
         // Linting and formatting
         "editorconfig.editorconfig",
         "charliermarsh.ruff",
-        "biomejs.biome"
-    ]
+        "biomejs.biome",
+    ],
 }

.vscode/launch.json

@@ -12,7 +12,7 @@
             "args": ["-M", "html", ".", "_build"],
             "cwd": "${workspaceFolder}/docs",
             "console": "internalConsole",
-            "justMyCode": false
+            "justMyCode": false,
         },
         {
             "name": "Python: Debug Test",
@@ -23,11 +23,11 @@
             "console": "internalConsole",
             "justMyCode": false,
             "env": {
-                "PYTEST_ADDOPTS": "--color=yes"
+                "PYTEST_ADDOPTS": "--color=yes",
             },
             "presentation": {
-                "hidden": true
-            }
-        }
-    ]
+                "hidden": true,
+            },
+        },
+    ],
 }

.vscode/settings.json

@@ -1,18 +1,18 @@
 {
     "[python][json][jsonc]": {
-        "editor.formatOnSave": true
+        "editor.formatOnSave": true,
     },
     "[python]": {
         "editor.defaultFormatter": "charliermarsh.ruff",
         "editor.codeActionsOnSave": {
             "source.fixAll": "always",
-            "source.organizeImports": "always"
-        }
+            "source.organizeImports": "always",
+        },
     },
     "[json][jsonc]": {
-        "editor.defaultFormatter": "biomejs.biome"
+        "editor.defaultFormatter": "biomejs.biome",
     },
     "python.analysis.typeCheckingMode": "basic",
     "python.testing.pytestEnabled": true,
-    "python.testing.pytestArgs": ["-vv", "--color=yes"]
+    "python.testing.pytestArgs": ["-vv", "--color=yes"],
 }

docs/conf.py

@@ -5,11 +5,14 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 # -- Path setup --------------------------------------------------------------
+import shutil
 import sys
 from datetime import datetime
 from importlib.metadata import metadata
 from pathlib import Path
 
+from sphinxcontrib import katex
+
 HERE = Path(__file__).parent
 sys.path.insert(0, str(HERE / "extensions"))
 
@@ -19,13 +22,12 @@
 # NOTE: If you installed your project in editable mode, this might be stale.
 #       If this is the case, reinstall it to refresh the metadata
 info = metadata("spatialdata-plot")
-project_name = info["Name"]
+project = info["Name"]
 author = info["Author"]
-copyright = f"{datetime.now():%Y}, {author}"
+copyright = f"{datetime.now():%Y}, {author}."
 version = info["Version"]
-
-# repository_url = f"https://github.com/scverse/{project_name}"
-
+urls = dict(pu.split(", ") for pu in info.get_all("Project-URL"))
+repository_url = urls["Source"]
 
 # The full version, including alpha/beta/rc tags
 release = info["Version"]
@@ -38,7 +40,7 @@
 html_context = {
     "display_github": True,  # Integrate GitHub
     "github_user": "scverse",
-    "github_repo": "https://github.com/scverse/spatialdata-plot",
+    "github_repo": project,
     "github_version": "main",
     "conf_py_path": "/docs/",
 }
@@ -55,23 +57,23 @@
     "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
     "sphinxcontrib.bibtex",
+    "sphinxcontrib.katex",
     "sphinx_autodoc_typehints",
-    "sphinx.ext.mathjax",
+    "sphinx_tabs.tabs",
     "IPython.sphinxext.ipython_console_highlighting",
-    "sphinx_design",
+    "sphinxext.opengraph",
     *[p.stem for p in (HERE / "extensions").glob("*.py")],
 ]
 
 autosummary_generate = True
-autodoc_process_signature = True
 autodoc_member_order = "groupwise"
 default_role = "literal"
 napoleon_google_docstring = False
 napoleon_numpy_docstring = True
 napoleon_include_init_with_doc = False
 napoleon_use_rtype = True  # having a separate entry generally helps readability
 napoleon_use_param = True
-myst_heading_anchors = 3  # create anchors for h1-h3
+myst_heading_anchors = 6  # create anchors for h1-h6
 myst_enable_extensions = [
     "amsmath",
     "colon_fence",
@@ -93,7 +95,9 @@
 }
 
 intersphinx_mapping = {
+    "python": ("https://docs.python.org/3.13", None),
     "anndata": ("https://anndata.readthedocs.io/en/stable/", None),
+    "scanpy": ("https://scanpy.readthedocs.io/en/stable/", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
     "geopandas": ("https://geopandas.org/en/stable/", None),
     "xarray": ("https://docs.xarray.dev/en/stable/", None),
@@ -108,18 +112,13 @@
 exclude_patterns = [
     "_build",
     "Thumbs.db",
+    ".DS_Store",
     "**.ipynb_checkpoints",
     "tutorials/notebooks/index.md",
     "tutorials/notebooks/README.md",
     "tutorials/notebooks/references.md",
     "tutorials/notebooks/notebooks/paper_reproducibility/*",
 ]
-# Ignore warnings.
-nitpicky = False  # TODO: solve upstream.
-# nitpick_ignore = [
-#     ("py:class", "spatial_image.SpatialImage"),
-#     ("py:class", "multiscale_spatial_image.multiscale_spatial_image.MultiscaleSpatialImage"),
-# ]
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -128,36 +127,26 @@
 # a list of builtin themes.
 #
 html_theme = "sphinx_book_theme"
-# html_theme = "sphinx_rtd_theme"
 html_static_path = ["_static"]
-html_title = project_name
+html_css_files = ["css/custom.css"]
+html_title = project
 html_logo = "_static/img/spatialdata_horizontal.png"
 
-# html_theme_options = {
-# "repository_url": repository_url,
-# "use_repository_button": True,
-# }
+html_theme_options = {
+    "repository_url": repository_url,
+    "use_repository_button": True,
+    "path_to_docs": "docs/",
+    "navigation_with_keys": False,
+}
 
 pygments_style = "default"
+katex_prerender = shutil.which(katex.NODEJS_BINARY) is not None
+
+# Ignore warnings.
+nitpicky = False  # TODO: solve upstream.
 
 nitpick_ignore = [
     # If building the documentation fails because of a missing link that is outside your control,
     # you can add an exception to this list.
     ("py:class", "igraph.Graph"),
 ]
-
-
-def setup(app):
-    """App setup hook."""
-    app.add_config_value(
-        "recommonmark_config",
-        {
-            "auto_toc_tree_section": "Contents",
-            "enable_auto_toc_tree": True,
-            "enable_math": True,
-            "enable_inline_math": False,
-            "enable_eval_rst": True,
-        },
-        True,
-    )
-    app.add_css_file("css/custom.css")