Wire pre-commit.ci, fix lint/execute drift, use canonical preview URL

Lint: ruff-format was collapsing the fluent .pl chains onto single lines
because they fit under 120 chars. Exclude *.ipynb from ruff-format; lint
notebooks via nbqa-ruff only.

Execute drift: pooch's tqdm.notebook spawns Jupyter widgets whose UUIDs
regenerate on every execution, breaking the diff-against-committed check.
Add scripts/strip_widget_metadata.py and run it as both a pre-commit hook
and a post-execute step in execute.yaml so committed and re-executed
notebooks stay symmetric.

pre-commit.ci: add the ci: config block so PRs are auto-fixed by the bot
(monthly autoupdate, autofix on every PR). Requires installing the
pre-commit.ci GitHub App on the repo (one-time, repo settings -> Apps).

Preview URL: the github.io URL 301-redirected through the scverse-org-wide
scverse.org CNAME, which made the displayed link confusingly different
from the destination. Switch the comment body to the canonical
https://scverse.org/<repo>/pr-N/gallery.html URL — same content, no
redirect.

Author: timtreis

.github/workflows/execute.yaml

@@ -76,6 +76,19 @@ jobs:
             jupyter nbconvert --to notebook --execute --inplace "$nb"
           done <<< "${{ steps.pick.outputs.files }}"
 
+      - name: Strip widget metadata
+        if: steps.pick.outputs.files != ''
+        # `pooch` and other libs spawn `tqdm.notebook` widgets when running
+        # in a Jupyter kernel; widget UUIDs regenerate on every execution and
+        # would cause spurious diff failures below. Same hook runs locally
+        # via .pre-commit-config.yaml so committed and re-executed notebooks
+        # stay symmetric.
+        run: |
+          while IFS= read -r nb; do
+            [ -z "$nb" ] && continue
+            python scripts/strip_widget_metadata.py "$nb" || true
+          done <<< "${{ steps.pick.outputs.files }}"
+
       - name: Diff outputs against committed
         if: steps.pick.outputs.files != ''
         run: |

.github/workflows/preview.yaml

@@ -69,7 +69,10 @@ jobs:
             const pr = context.issue.number;
             const owner = context.repo.owner;
             const repo = context.repo.repo;
-            const url = `https://${owner}.github.io/${repo}/pr-${pr}/gallery.html`;
+            // Use the canonical scverse.org URL directly. The github.io URL
+            // 301-redirects there because of the org-wide CNAME, which makes
+            // the displayed link confusingly different from the destination.
+            const url = `https://scverse.org/${repo}/pr-${pr}/gallery.html`;
             const marker = '<!-- preview-link -->';
             const body = `${marker}\n📖 **Docs preview**: ${url}\n\n_Built from ${context.sha.substring(0, 7)}; redeployed on every push._`;
             const { data: comments } = await github.rest.issues.listComments({ owner, repo, issue_number: pr });

.pre-commit-config.yaml

@@ -1,3 +1,19 @@
+# pre-commit config. Auto-run on PRs by pre-commit.ci (see ci: block below);
+# run locally with `pre-commit run --all-files` after `pip install pre-commit`.
+
+ci:
+  # Auto-fix PRs where possible; tag the commit so it's clearly bot-authored.
+  autofix_commit_msg: |
+    [pre-commit.ci] auto fixes from pre-commit.com hooks
+
+    for more information, see https://pre-commit.ci
+  autofix_prs: true
+  autoupdate_branch: ""
+  autoupdate_commit_msg: "[pre-commit.ci] pre-commit autoupdate"
+  autoupdate_schedule: monthly
+  skip: []
+  submodules: false
+
 fail_fast: false
 default_language_version:
   python: python3
@@ -25,9 +41,22 @@ repos:
       - id: ruff
         args: [--fix]
       - id: ruff-format
+        # Notebook cells use a chained fluent API; ruff-format collapses
+        # short chains onto one line which hurts readability. Lint notebooks
+        # via nbqa-ruff (below) instead.
+        exclude: \.ipynb$
 
   - repo: https://github.com/nbQA-dev/nbQA
     rev: 1.9.0
     hooks:
       - id: nbqa-ruff
         args: [--fix]
+
+  - repo: local
+    hooks:
+      - id: strip-widget-metadata
+        name: Strip Jupyter widget metadata from notebooks
+        entry: python scripts/strip_widget_metadata.py
+        language: system
+        files: \.ipynb$
+        require_serial: false

scripts/strip_widget_metadata.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+"""Strip Jupyter widget metadata + outputs from .ipynb files.
+
+Widget UUIDs are regenerated on every execution, so any notebook that runs
+something using `tqdm.notebook` (e.g. `pooch` downloads, `scanpy` progress
+bars in a Jupyter kernel) drifts on every re-execution. Stripping widgets
+makes the diff-against-committed check in `execute.yaml` deterministic, and
+keeps committed notebooks reproducible without losing the visible outputs
+(figures, repr cells, prints).
+
+Usage: strip_widget_metadata.py <notebook> [<notebook> ...]
+Exits 0 if no changes, 1 if files were modified (so pre-commit reports the
+fix the way other auto-fixers do).
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+WIDGET_MIME = "application/vnd.jupyter.widget-view+json"
+
+
+def strip(path: Path) -> bool:
+    nb = json.loads(path.read_text())
+    changed = False
+
+    if "widgets" in nb.get("metadata", {}):
+        nb["metadata"].pop("widgets")
+        changed = True
+
+    for cell in nb.get("cells", []):
+        for output in cell.get("outputs", []):
+            data = output.get("data", {})
+            if WIDGET_MIME in data:
+                data.pop(WIDGET_MIME)
+                changed = True
+
+    if changed:
+        path.write_text(json.dumps(nb, indent=1) + "\n")
+    return changed
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        print("usage: strip_widget_metadata.py <notebook> [<notebook> ...]", file=sys.stderr)
+        return 2
+    any_changed = False
+    for arg in sys.argv[1:]:
+        if strip(Path(arg)):
+            print(f"stripped widgets: {arg}")
+            any_changed = True
+    return 1 if any_changed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tutorials/visium_breast_cancer.ipynb

@@ -9,9 +9,9 @@
     "\n",
     "This tutorial walks through visualising a real 10x Genomics Visium experiment with `spatialdata-plot`: H&E tissue image, spot polygons, gene expression overlays, and publication-style styling.\n",
     "\n",
-    "**Dataset**: [Human Breast Cancer (Block A Section 1)][10x] from 10x Genomics — fetched once via `scanpy.datasets.visium_sge` and cached by `pooch` for subsequent runs.\n",
+    "**Dataset**: [Human Breast Cancer (Block A Section 1)][10x] from 10x Genomics \u2014 fetched once via `scanpy.datasets.visium_sge` and cached by `pooch` for subsequent runs.\n",
     "\n",
-    "**Credit**: the example progression in this tutorial — H&E + spots, gene-expression overlays, outline styling — was originally curated by [@asarigun](https://github.com/asarigun) in [scverse/spatialdata-plot#590](https://github.com/scverse/spatialdata-plot/pull/590).\n",
+    "**Credit**: the example progression in this tutorial \u2014 H&E + spots, gene-expression overlays, outline styling \u2014 was originally curated by [@asarigun](https://github.com/asarigun) in [scverse/spatialdata-plot#590](https://github.com/scverse/spatialdata-plot/pull/590).\n",
     "\n",
     "[10x]: https://www.10xgenomics.com/datasets/human-breast-cancer-block-a-section-1-1-standard-1-1-0"
    ]
@@ -43,14 +43,14 @@
      "data": {
       "text/plain": [
        "SpatialData object\n",
-       "├── Images\n",
-       "│     └── 'tissue': DataArray[cyx] (3, 2000, 2000)\n",
-       "├── Shapes\n",
-       "│     └── 'spots': GeoDataFrame shape: (3798, 2) (2D shapes)\n",
-       "└── Tables\n",
-       "      └── 'table': AnnData (3798, 36601)\n",
+       "\u251c\u2500\u2500 Images\n",
+       "\u2502     \u2514\u2500\u2500 'tissue': DataArray[cyx] (3, 2000, 2000)\n",
+       "\u251c\u2500\u2500 Shapes\n",
+       "\u2502     \u2514\u2500\u2500 'spots': GeoDataFrame shape: (3798, 2) (2D shapes)\n",
+       "\u2514\u2500\u2500 Tables\n",
+       "      \u2514\u2500\u2500 'table': AnnData (3798, 36601)\n",
        "with coordinate systems:\n",
-       "    ▸ 'global', with elements:\n",
+       "    \u25b8 'global', with elements:\n",
        "        tissue (Images), spots (Shapes)"
       ]
      },
@@ -283,7 +283,7 @@
    "source": [
     "## Coloring spots by a category\n",
     "\n",
-    "`color=` also accepts categorical columns — here, the `in_tissue` flag 10x sets to mark spots that fall on tissue."
+    "`color=` also accepts categorical columns \u2014 here, the `in_tissue` flag 10x sets to mark spots that fall on tissue."
    ]
   },
   {
@@ -375,9 +375,9 @@
    "source": [
     "## Where to next\n",
     "\n",
-    "- **API reference** — every parameter of `render_shapes`, `render_images`, and `show()` is documented in the [plotting API](https://spatialdata.scverse.org/projects/plot/en/latest/api.html).\n",
-    "- **Getting started tutorial** — if you skipped it, the [Getting started](./getting_started.ipynb) tutorial covers the same fluent API on the lightweight built-in `blobs` dataset.\n",
-    "- **Contributing** — found a missing example? Open a PR on [`spatialdata-plot-notebooks`](https://github.com/scverse/spatialdata-plot-notebooks)."
+    "- **API reference** \u2014 every parameter of `render_shapes`, `render_images`, and `show()` is documented in the [plotting API](https://spatialdata.scverse.org/projects/plot/en/latest/api.html).\n",
+    "- **Getting started tutorial** \u2014 if you skipped it, the [Getting started](./getting_started.ipynb) tutorial covers the same fluent API on the lightweight built-in `blobs` dataset.\n",
+    "- **Contributing** \u2014 found a missing example? Open a PR on [`spatialdata-plot-notebooks`](https://github.com/scverse/spatialdata-plot-notebooks)."
    ]
   }
  ],