Bootstrap notebooks repo with getting-started tutorial

- Scaffold pyproject (exec/dev extras), README, CONTRIBUTING, .gitignore.
- Add lint + execute CI workflows; weekly re-execution against latest release.
- Add tutorials/getting_started.ipynb using sd.datasets.blobs() (executed,
  outputs committed) covering fluent .pl API, layering, and styling.
- Add tutorials/ and examples/ index landing pages for sphinx toctree.

Author: timtreis

.github/workflows/execute.yaml

@@ -0,0 +1,64 @@
+name: Execute notebooks
+
+on:
+  schedule:
+    # Weekly: Mondays 04:00 UTC
+    - cron: "0 4 * * 1"
+  pull_request:
+    branches: [main]
+    paths:
+      - "**/*.ipynb"
+      - "pyproject.toml"
+      - ".github/workflows/execute.yaml"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  execute:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          # Need full history so nbdime can diff against base.
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Cache pooch datasets
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pooch
+          key: pooch-${{ runner.os }}-${{ hashFiles('**/*.ipynb') }}
+          restore-keys: |
+            pooch-${{ runner.os }}-
+
+      - name: Install execution environment
+        run: |
+          pip install --upgrade pip
+          pip install -e ".[exec]" nbdime jupyter
+
+      - name: Re-execute notebooks
+        run: |
+          # Find every notebook under tutorials/ and examples/, execute in
+          # place, fail on any cell error.
+          find tutorials examples -name "*.ipynb" -not -path "*/.ipynb_checkpoints/*" | while read -r nb; do
+            echo "Executing $nb"
+            jupyter nbconvert --to notebook --execute --inplace "$nb"
+          done
+
+      - name: Diff outputs against committed
+        run: |
+          # If outputs drift from what's committed, fail the job. Authors are
+          # expected to commit re-executed notebooks; CI catches drift between
+          # commits (e.g., upstream lib changes).
+          if ! git diff --quiet -- '*.ipynb'; then
+            echo "Notebook outputs drifted from committed state:"
+            nbdime diff
+            exit 1
+          fi

.github/workflows/lint.yaml

@@ -0,0 +1,32 @@
+name: Lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - uses: actions/cache@v4
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ runner.os }}-${{ hashFiles('.pre-commit-config.yaml') }}
+
+      - name: Install pre-commit
+        run: pip install pre-commit
+
+      - name: Run pre-commit
+        run: pre-commit run --all-files --show-diff-on-failure

.gitignore

@@ -0,0 +1,40 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+
+# Editors
+.idea/
+.vscode/
+.DS_Store
+
+# Jupyter
+.ipynb_checkpoints/
+profile_default/
+ipython_config.py
+
+# Caches
+.cache/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Datasets cached on first run
+data/
+tutorial_data/
+
+# Sphinx build artifacts (in case anyone builds locally)
+docs/_build/

.pre-commit-config.yaml

@@ -0,0 +1,33 @@
+fail_fast: false
+default_language_version:
+  python: python3
+minimum_pre_commit_version: 3.0.0
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-yaml
+      - id: check-toml
+      - id: end-of-file-fixer
+        exclude: \.ipynb$
+      - id: mixed-line-ending
+        args: [--fix=lf]
+      - id: trailing-whitespace
+        exclude: \.ipynb$
+      - id: check-added-large-files
+        args: [--maxkb=5000]
+        exclude: \.ipynb$
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.7.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/nbQA-dev/nbQA
+    rev: 1.9.0
+    hooks:
+      - id: nbqa-ruff
+        args: [--fix]

CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing
+
+Thanks for contributing a notebook to the `spatialdata-plot` gallery.
+
+## Setup
+
+```bash
+git clone https://github.com/scverse/spatialdata-plot-notebooks.git
+cd spatialdata-plot-notebooks
+pip install -e ".[exec,dev]"
+pre-commit install
+```
+
+## Adding a notebook
+
+1. Decide the type:
+   - **`tutorials/<topic>.ipynb`** — end-to-end workflow on a real dataset
+     (Visium, Xenium, MERFISH, …). Focuses on a complete analysis story.
+   - **`examples/<group>/<topic>.ipynb`** — short, single-feature notebook
+     (e.g., `examples/customization/outlines.ipynb`). Focuses on one technique.
+
+2. Start the notebook with a markdown cell containing:
+   - A title (`# ...`).
+   - 2-3 sentences on what the reader will learn.
+   - A dataset citation when applicable.
+
+3. Use `squidpy.datasets.*` or `spatialdata.datasets.*` for data — never raw
+   URLs. Both libraries cache via `pooch`, so first-run downloads are cheap on
+   re-runs.
+
+4. Re-execute the notebook end-to-end (Restart Kernel & Run All) and commit
+   with outputs. The `spatialdata-plot` docs build performs no execution; what
+   you commit is what users see rendered.
+
+5. Add the notebook to the appropriate `index.md` so it appears in the gallery
+   toctree.
+
+6. Open a PR. CI will:
+   - Lint structure and code (`lint.yaml`).
+   - Re-execute the notebook against the latest `spatialdata-plot` release
+     and diff outputs (`execute.yaml`).
+
+## Updating an existing notebook
+
+Edit, re-execute, commit. CI catches output drift on the next scheduled run if
+you forget.
+
+## What not to commit
+
+- Raw datasets (use `squidpy.datasets` / `spatialdata.datasets`).
+- Notebooks larger than ~5 MB after execution — open an issue first; we may
+  need git-lfs or a downsampled variant.
+- Cells that depend on local files outside the repo.
+
+## Questions
+
+Open an issue or ping in [scverse Zulip](https://scverse.zulipchat.com).

README.md

@@ -0,0 +1,53 @@
+# spatialdata-plot-notebooks
+
+Executable notebooks demonstrating [spatialdata-plot] on real spatial-omics
+datasets. Rendered into the [spatialdata-plot documentation][docs] as a
+gallery.
+
+[spatialdata-plot]: https://github.com/scverse/spatialdata-plot
+[docs]: https://spatialdata.scverse.org/projects/plot/en/latest/
+
+## Layout
+
+```
+tutorials/   # end-to-end workflows on real datasets (Visium, Xenium, MERFISH, ...)
+examples/    # short, focused notebooks demonstrating one feature at a time
+```
+
+Each notebook is committed **with outputs** so the `spatialdata-plot` docs build
+performs no execution. Outputs are kept fresh by a scheduled CI job that
+re-executes every notebook against the latest `spatialdata-plot` release.
+
+## Running notebooks locally
+
+```bash
+git clone https://github.com/scverse/spatialdata-plot-notebooks.git
+cd spatialdata-plot-notebooks
+pip install -e ".[exec]"
+jupyter lab
+```
+
+The `exec` extra pulls `spatialdata-plot`, `squidpy` (for dataset loaders),
+and `jupyter`. Datasets are fetched on first run via each library's built-in
+caching (`pooch`), then re-used across runs.
+
+## Contributing a notebook
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Short version:
+
+1. Add `tutorials/<topic>.ipynb` (workflow) or `examples/<group>/<topic>.ipynb`
+   (focused).
+2. Re-execute end-to-end and commit with outputs.
+3. Add the notebook to `tutorials/index.md` or `examples/index.md`.
+4. Open a PR — `lint.yaml` checks structure; `execute.yaml` re-runs notebooks
+   on the PR.
+
+## Datasets and attribution
+
+Notebooks use public datasets distributed via `squidpy.datasets` and
+`spatialdata.datasets`. Per-dataset citations live in the markdown header of
+each notebook; please follow the same convention when contributing.
+
+## License
+
+BSD-3-Clause. See [LICENSE](LICENSE).

examples/index.md

@@ -0,0 +1,12 @@
+# Examples
+
+Short, focused notebooks demonstrating individual `spatialdata-plot` features.
+Use these as a quick reference when you know what you want to do and need to
+see the call shape.
+
+```{toctree}
+:maxdepth: 2
+:glob:
+
+*/index
+```

pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "spatialdata-plot-notebooks"
+version = "0.0.0"
+description = "Executable notebooks demonstrating spatialdata-plot on real spatial-omics datasets."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.11"
+authors = [{ name = "scverse" }]
+
+# The package itself ships no Python code; this is a pyproject for tooling +
+# environment management. The `exec` extra installs everything needed to run
+# the notebooks end-to-end.
+[project.optional-dependencies]
+exec = [
+    "spatialdata-plot>=0.3",
+    "squidpy",
+    "jupyter",
+    "ipykernel",
+]
+dev = [
+    "pre-commit>=3.0",
+    "ruff",
+    "nbstripout",
+]
+
+[project.urls]
+Source = "https://github.com/scverse/spatialdata-plot-notebooks"
+Documentation = "https://spatialdata.scverse.org/projects/plot/en/latest/"
+
+[tool.hatch.build.targets.wheel]
+bypass-selection = true
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B"]
+ignore = ["E501"]  # long lines fine in notebooks
+
+[tool.ruff.lint.per-file-ignores]
+"*.ipynb" = ["E402"]  # imports after markdown intro cells are common