Add docs gallery via spatialdata-plot-notebooks submodule by timtreis · Pull Request #656 · scverse/spatialdata-plot

timtreis · 2026-05-11T14:55:51Z

Inspired by #590 by user asarigun

Summary

Mounts scverse/spatialdata-plot-notebooks at docs/notebooks/ as a git submodule and renders it into the docs as a new Gallery section. Follows the scverse convention used by anndata, spatialdata, scvi-tools, and squidpy (pre-rendered notebooks via myst-nb, nb_execution_mode = "off").

This supersedes the sphinx-gallery approach proposed in #590 — see "Why this approach" below — and addresses the missing-gallery gap identified in #463.

Changes

File	Change
`.gitmodules`	New submodule `docs/notebooks` → `scverse/spatialdata-plot-notebooks` (branch `main`).
`docs/gallery.md`	New gallery landing page with toctree pointing at the submodule's `tutorials/index` and `examples/index`.
`docs/index.md`	Add `gallery.md` to the top-level toctree.
`docs/conf.py`	`exclude_patterns`: drop stale `tutorials/notebooks/...` entries (dir was never created); exclude submodule meta-files (README, CONTRIBUTING, LICENSE, .github, pyproject.toml) so they don't trigger toctree warnings.
`.readthedocs.yaml`	`submodules: include: all` so RTD pulls the notebooks repo on each build.
`.github/workflows/build.yaml`	New `docs` job that builds docs on every PR with submodules checked out — first time docs builds are PR-gated.

No new dependencies. The notebooks repo's pyproject.toml carries squidpy and other heavy tutorial deps; this repo's doc group is unchanged.

Why this approach

Matches every scverse neighbor. anndata, spatialdata, scvi-tools, squidpy all use the same submodule-to-*-notebooks-repo pattern with nb_execution_mode = "off". Sphinx-gallery is unused across scverse.
Zero network and zero execution at lib doc-build time. The getting_started.ipynb already shipped in the notebooks repo runs sd.datasets.blobs() (in-memory, no download). Heavier tutorials (Visium, Xenium, MERFISH) will fetch via squidpy.datasets.* when contributors execute them locally — the docs build only renders pre-committed outputs.
Decouples notebook freshness from lib release cycle. The notebooks repo's execute.yaml workflow re-executes every notebook weekly (and on PR) against the latest spatialdata-plot release, catching silent regressions via nbdime diff without blocking lib PRs.
Lib repo stays light. No 1+ MB executed notebooks in the lib's git history; all notebook content lives in the dedicated repo where it can grow.

Mounts scverse/spatialdata-plot-notebooks at docs/notebooks/ and renders it into the docs as a Gallery section, following the scverse convention used by anndata, spatialdata, scvi-tools, and squidpy. Notebooks are pre-executed by humans and committed with outputs in the notebooks repo; this docs build performs no execution. RTD pulls the submodule on each build (submodules.include = all). A new `docs` job in build.yaml runs the docs build on every PR with submodules checked out, gating sphinx warnings (-W) before merge. conf.py exclude_patterns: drop stale `tutorials/notebooks/...` entries (directory was never created), exclude submodule meta-files (README, CONTRIBUTING, LICENSE, .github, pyproject.toml) so they don't trigger toctree warnings. Closes the gallery scope from #463; supersedes the sphinx-gallery approach proposed in #590.

codecov-commenter · 2026-05-11T15:05:09Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.07%. Comparing base (e5c54fd) to head (75de4cc).

Additional details and impacted files

@@ Coverage Diff @@## main #656 +/- ##
==========================================
+ Coverage 77.04% 77.07% +0.03% 
==========================================
Files 11 11 Lines 3280 3280 Branches 774 774 ==========================================
+ Hits 2527 2528 +1 
Misses 454 454 + Partials 299 298 -1

see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Replaces the now-stale "Tutorials with myst-nb" section with concrete instructions for the submodule-based gallery: how to clone with submodules, how to bump the pin, and where to send notebook PRs (the notebooks repo). Adds a heads-up admonition to the "Building the docs locally" section so contributors who cloned without --recurse-submodules know to run `git submodule update --init --recursive` before sphinx-build.

C2 — Render notebooks-repo main, not the pinned SHA .readthedocs.yaml gains a `post_checkout` job that runs `git submodule update --init --remote --recursive` so RTD always renders the latest gallery without requiring a submodule-bump PR here. Mirrored in the docs CI job in build.yaml. Trade-off: docs at older lib tags are no longer bit-for-bit reproducible for the gallery. N1 — Card gallery with thumbnails (matches scverse/spatialdata) Add sphinx-design to doc deps and to the extension list. Rewrite gallery.md to use {grid}/{grid-item-card} with an :img-top: thumbnail. Thumbnail PNG (getting_started.png) committed under docs/_static/gallery. N6 — README points at the gallery New `link-gallery` link target alongside the existing API reference; existing spatialdata-notebooks link reframed as a "broader analyses" pointer. Fixes the "Visiualizations" typo while there.

timtreis · 2026-05-11T14:55:51Z

Inspired by #590 by user asarigun

Summary

Mounts scverse/spatialdata-plot-notebooks at docs/notebooks/ as a git submodule and renders it into the docs as a new Gallery section. Follows the scverse convention used by anndata, spatialdata, scvi-tools, and squidpy (pre-rendered notebooks via myst-nb, nb_execution_mode = "off").

This supersedes the sphinx-gallery approach proposed in #590 — see "Why this approach" below — and addresses the missing-gallery gap identified in #463.

Changes

File	Change
`.gitmodules`	New submodule `docs/notebooks` → `scverse/spatialdata-plot-notebooks` (branch `main`).
`docs/gallery.md`	New gallery landing page with toctree pointing at the submodule's `tutorials/index` and `examples/index`.
`docs/index.md`	Add `gallery.md` to the top-level toctree.
`docs/conf.py`	`exclude_patterns`: drop stale `tutorials/notebooks/...` entries (dir was never created); exclude submodule meta-files (README, CONTRIBUTING, LICENSE, .github, pyproject.toml) so they don't trigger toctree warnings.
`.readthedocs.yaml`	`submodules: include: all` so RTD pulls the notebooks repo on each build.
`.github/workflows/build.yaml`	New `docs` job that builds docs on every PR with submodules checked out — first time docs builds are PR-gated.

No new dependencies. The notebooks repo's pyproject.toml carries squidpy and other heavy tutorial deps; this repo's doc group is unchanged.

Why this approach

Matches every scverse neighbor. anndata, spatialdata, scvi-tools, squidpy all use the same submodule-to-*-notebooks-repo pattern with nb_execution_mode = "off". Sphinx-gallery is unused across scverse.
Zero network and zero execution at lib doc-build time. The getting_started.ipynb already shipped in the notebooks repo runs sd.datasets.blobs() (in-memory, no download). Heavier tutorials (Visium, Xenium, MERFISH) will fetch via squidpy.datasets.* when contributors execute them locally — the docs build only renders pre-committed outputs.
Decouples notebook freshness from lib release cycle. The notebooks repo's execute.yaml workflow re-executes every notebook weekly (and on PR) against the latest spatialdata-plot release, catching silent regressions via nbdime diff without blocking lib PRs.
Lib repo stays light. No 1+ MB executed notebooks in the lib's git history; all notebook content lives in the dedicated repo where it can grow.

Mounts scverse/spatialdata-plot-notebooks at docs/notebooks/ and renders it into the docs as a Gallery section, following the scverse convention used by anndata, spatialdata, scvi-tools, and squidpy. Notebooks are pre-executed by humans and committed with outputs in the notebooks repo; this docs build performs no execution. RTD pulls the submodule on each build (submodules.include = all). A new `docs` job in build.yaml runs the docs build on every PR with submodules checked out, gating sphinx warnings (-W) before merge. conf.py exclude_patterns: drop stale `tutorials/notebooks/...` entries (directory was never created), exclude submodule meta-files (README, CONTRIBUTING, LICENSE, .github, pyproject.toml) so they don't trigger toctree warnings. Closes the gallery scope from #463; supersedes the sphinx-gallery approach proposed in #590.

codecov-commenter · 2026-05-11T15:05:09Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.07%. Comparing base (e5c54fd) to head (75de4cc).

Additional details and impacted files

@@ Coverage Diff @@## main #656 +/- ##
==========================================
+ Coverage 77.04% 77.07% +0.03% 
==========================================
Files 11 11 Lines 3280 3280 Branches 774 774 ==========================================
+ Hits 2527 2528 +1 
Misses 454 454 + Partials 299 298 -1

see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Replaces the now-stale "Tutorials with myst-nb" section with concrete instructions for the submodule-based gallery: how to clone with submodules, how to bump the pin, and where to send notebook PRs (the notebooks repo). Adds a heads-up admonition to the "Building the docs locally" section so contributors who cloned without --recurse-submodules know to run `git submodule update --init --recursive` before sphinx-build.

C2 — Render notebooks-repo main, not the pinned SHA .readthedocs.yaml gains a `post_checkout` job that runs `git submodule update --init --remote --recursive` so RTD always renders the latest gallery without requiring a submodule-bump PR here. Mirrored in the docs CI job in build.yaml. Trade-off: docs at older lib tags are no longer bit-for-bit reproducible for the gallery. N1 — Card gallery with thumbnails (matches scverse/spatialdata) Add sphinx-design to doc deps and to the extension list. Rewrite gallery.md to use {grid}/{grid-item-card} with an :img-top: thumbnail. Thumbnail PNG (getting_started.png) committed under docs/_static/gallery. N6 — README points at the gallery New `link-gallery` link target alongside the existing API reference; existing spatialdata-notebooks link reframed as a "broader analyses" pointer. Fixes the "Visiualizations" typo while there.

timtreis · 2026-05-11T14:55:51Z

Inspired by #590 by user asarigun

Summary

Mounts scverse/spatialdata-plot-notebooks at docs/notebooks/ as a git submodule and renders it into the docs as a new Gallery section. Follows the scverse convention used by anndata, spatialdata, scvi-tools, and squidpy (pre-rendered notebooks via myst-nb, nb_execution_mode = "off").

This supersedes the sphinx-gallery approach proposed in #590 — see "Why this approach" below — and addresses the missing-gallery gap identified in #463.

Changes

File	Change
`.gitmodules`	New submodule `docs/notebooks` → `scverse/spatialdata-plot-notebooks` (branch `main`).
`docs/gallery.md`	New gallery landing page with toctree pointing at the submodule's `tutorials/index` and `examples/index`.
`docs/index.md`	Add `gallery.md` to the top-level toctree.
`docs/conf.py`	`exclude_patterns`: drop stale `tutorials/notebooks/...` entries (dir was never created); exclude submodule meta-files (README, CONTRIBUTING, LICENSE, .github, pyproject.toml) so they don't trigger toctree warnings.
`.readthedocs.yaml`	`submodules: include: all` so RTD pulls the notebooks repo on each build.
`.github/workflows/build.yaml`	New `docs` job that builds docs on every PR with submodules checked out — first time docs builds are PR-gated.

No new dependencies. The notebooks repo's pyproject.toml carries squidpy and other heavy tutorial deps; this repo's doc group is unchanged.

Why this approach

Matches every scverse neighbor. anndata, spatialdata, scvi-tools, squidpy all use the same submodule-to-*-notebooks-repo pattern with nb_execution_mode = "off". Sphinx-gallery is unused across scverse.
Zero network and zero execution at lib doc-build time. The getting_started.ipynb already shipped in the notebooks repo runs sd.datasets.blobs() (in-memory, no download). Heavier tutorials (Visium, Xenium, MERFISH) will fetch via squidpy.datasets.* when contributors execute them locally — the docs build only renders pre-committed outputs.
Decouples notebook freshness from lib release cycle. The notebooks repo's execute.yaml workflow re-executes every notebook weekly (and on PR) against the latest spatialdata-plot release, catching silent regressions via nbdime diff without blocking lib PRs.
Lib repo stays light. No 1+ MB executed notebooks in the lib's git history; all notebook content lives in the dedicated repo where it can grow.

Mounts scverse/spatialdata-plot-notebooks at docs/notebooks/ and renders it into the docs as a Gallery section, following the scverse convention used by anndata, spatialdata, scvi-tools, and squidpy. Notebooks are pre-executed by humans and committed with outputs in the notebooks repo; this docs build performs no execution. RTD pulls the submodule on each build (submodules.include = all). A new `docs` job in build.yaml runs the docs build on every PR with submodules checked out, gating sphinx warnings (-W) before merge. conf.py exclude_patterns: drop stale `tutorials/notebooks/...` entries (directory was never created), exclude submodule meta-files (README, CONTRIBUTING, LICENSE, .github, pyproject.toml) so they don't trigger toctree warnings. Closes the gallery scope from #463; supersedes the sphinx-gallery approach proposed in #590.

codecov-commenter · 2026-05-11T15:05:09Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.07%. Comparing base (e5c54fd) to head (75de4cc).

Additional details and impacted files

@@ Coverage Diff @@## main #656 +/- ##
==========================================
+ Coverage 77.04% 77.07% +0.03% 
==========================================
Files 11 11 Lines 3280 3280 Branches 774 774 ==========================================
+ Hits 2527 2528 +1 
Misses 454 454 + Partials 299 298 -1

see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Replaces the now-stale "Tutorials with myst-nb" section with concrete instructions for the submodule-based gallery: how to clone with submodules, how to bump the pin, and where to send notebook PRs (the notebooks repo). Adds a heads-up admonition to the "Building the docs locally" section so contributors who cloned without --recurse-submodules know to run `git submodule update --init --recursive` before sphinx-build.

C2 — Render notebooks-repo main, not the pinned SHA .readthedocs.yaml gains a `post_checkout` job that runs `git submodule update --init --remote --recursive` so RTD always renders the latest gallery without requiring a submodule-bump PR here. Mirrored in the docs CI job in build.yaml. Trade-off: docs at older lib tags are no longer bit-for-bit reproducible for the gallery. N1 — Card gallery with thumbnails (matches scverse/spatialdata) Add sphinx-design to doc deps and to the extension list. Rewrite gallery.md to use {grid}/{grid-item-card} with an :img-top: thumbnail. Thumbnail PNG (getting_started.png) committed under docs/_static/gallery. N6 — README points at the gallery New `link-gallery` link target alongside the existing API reference; existing spatialdata-notebooks link reframed as a "broader analyses" pointer. Fixes the "Visiualizations" typo while there.

timtreis · 2026-05-11T14:55:51Z

Inspired by #590 by user asarigun

Summary

Mounts scverse/spatialdata-plot-notebooks at docs/notebooks/ as a git submodule and renders it into the docs as a new Gallery section. Follows the scverse convention used by anndata, spatialdata, scvi-tools, and squidpy (pre-rendered notebooks via myst-nb, nb_execution_mode = "off").

This supersedes the sphinx-gallery approach proposed in #590 — see "Why this approach" below — and addresses the missing-gallery gap identified in #463.

Changes

File	Change
`.gitmodules`	New submodule `docs/notebooks` → `scverse/spatialdata-plot-notebooks` (branch `main`).
`docs/gallery.md`	New gallery landing page with toctree pointing at the submodule's `tutorials/index` and `examples/index`.
`docs/index.md`	Add `gallery.md` to the top-level toctree.
`docs/conf.py`	`exclude_patterns`: drop stale `tutorials/notebooks/...` entries (dir was never created); exclude submodule meta-files (README, CONTRIBUTING, LICENSE, .github, pyproject.toml) so they don't trigger toctree warnings.
`.readthedocs.yaml`	`submodules: include: all` so RTD pulls the notebooks repo on each build.
`.github/workflows/build.yaml`	New `docs` job that builds docs on every PR with submodules checked out — first time docs builds are PR-gated.

No new dependencies. The notebooks repo's pyproject.toml carries squidpy and other heavy tutorial deps; this repo's doc group is unchanged.

Why this approach

Matches every scverse neighbor. anndata, spatialdata, scvi-tools, squidpy all use the same submodule-to-*-notebooks-repo pattern with nb_execution_mode = "off". Sphinx-gallery is unused across scverse.
Zero network and zero execution at lib doc-build time. The getting_started.ipynb already shipped in the notebooks repo runs sd.datasets.blobs() (in-memory, no download). Heavier tutorials (Visium, Xenium, MERFISH) will fetch via squidpy.datasets.* when contributors execute them locally — the docs build only renders pre-committed outputs.
Decouples notebook freshness from lib release cycle. The notebooks repo's execute.yaml workflow re-executes every notebook weekly (and on PR) against the latest spatialdata-plot release, catching silent regressions via nbdime diff without blocking lib PRs.
Lib repo stays light. No 1+ MB executed notebooks in the lib's git history; all notebook content lives in the dedicated repo where it can grow.

Mounts scverse/spatialdata-plot-notebooks at docs/notebooks/ and renders it into the docs as a Gallery section, following the scverse convention used by anndata, spatialdata, scvi-tools, and squidpy. Notebooks are pre-executed by humans and committed with outputs in the notebooks repo; this docs build performs no execution. RTD pulls the submodule on each build (submodules.include = all). A new `docs` job in build.yaml runs the docs build on every PR with submodules checked out, gating sphinx warnings (-W) before merge. conf.py exclude_patterns: drop stale `tutorials/notebooks/...` entries (directory was never created), exclude submodule meta-files (README, CONTRIBUTING, LICENSE, .github, pyproject.toml) so they don't trigger toctree warnings. Closes the gallery scope from #463; supersedes the sphinx-gallery approach proposed in #590.

codecov-commenter · 2026-05-11T15:05:09Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.07%. Comparing base (e5c54fd) to head (75de4cc).

Additional details and impacted files

@@ Coverage Diff @@## main #656 +/- ##
==========================================
+ Coverage 77.04% 77.07% +0.03% 
==========================================
Files 11 11 Lines 3280 3280 Branches 774 774 ==========================================
+ Hits 2527 2528 +1 
Misses 454 454 + Partials 299 298 -1

see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Replaces the now-stale "Tutorials with myst-nb" section with concrete instructions for the submodule-based gallery: how to clone with submodules, how to bump the pin, and where to send notebook PRs (the notebooks repo). Adds a heads-up admonition to the "Building the docs locally" section so contributors who cloned without --recurse-submodules know to run `git submodule update --init --recursive` before sphinx-build.

C2 — Render notebooks-repo main, not the pinned SHA .readthedocs.yaml gains a `post_checkout` job that runs `git submodule update --init --remote --recursive` so RTD always renders the latest gallery without requiring a submodule-bump PR here. Mirrored in the docs CI job in build.yaml. Trade-off: docs at older lib tags are no longer bit-for-bit reproducible for the gallery. N1 — Card gallery with thumbnails (matches scverse/spatialdata) Add sphinx-design to doc deps and to the extension list. Rewrite gallery.md to use {grid}/{grid-item-card} with an :img-top: thumbnail. Thumbnail PNG (getting_started.png) committed under docs/_static/gallery. N6 — README points at the gallery New `link-gallery` link target alongside the existing API reference; existing spatialdata-notebooks link reframed as a "broader analyses" pointer. Fixes the "Visiualizations" typo while there.

timtreis · 2026-05-11T14:55:51Z

Inspired by #590 by user asarigun

Summary

Mounts scverse/spatialdata-plot-notebooks at docs/notebooks/ as a git submodule and renders it into the docs as a new Gallery section. Follows the scverse convention used by anndata, spatialdata, scvi-tools, and squidpy (pre-rendered notebooks via myst-nb, nb_execution_mode = "off").

This supersedes the sphinx-gallery approach proposed in #590 — see "Why this approach" below — and addresses the missing-gallery gap identified in #463.

Changes

File	Change
`.gitmodules`	New submodule `docs/notebooks` → `scverse/spatialdata-plot-notebooks` (branch `main`).
`docs/gallery.md`	New gallery landing page with toctree pointing at the submodule's `tutorials/index` and `examples/index`.
`docs/index.md`	Add `gallery.md` to the top-level toctree.
`docs/conf.py`	`exclude_patterns`: drop stale `tutorials/notebooks/...` entries (dir was never created); exclude submodule meta-files (README, CONTRIBUTING, LICENSE, .github, pyproject.toml) so they don't trigger toctree warnings.
`.readthedocs.yaml`	`submodules: include: all` so RTD pulls the notebooks repo on each build.
`.github/workflows/build.yaml`	New `docs` job that builds docs on every PR with submodules checked out — first time docs builds are PR-gated.

No new dependencies. The notebooks repo's pyproject.toml carries squidpy and other heavy tutorial deps; this repo's doc group is unchanged.

Why this approach

Matches every scverse neighbor. anndata, spatialdata, scvi-tools, squidpy all use the same submodule-to-*-notebooks-repo pattern with nb_execution_mode = "off". Sphinx-gallery is unused across scverse.
Zero network and zero execution at lib doc-build time. The getting_started.ipynb already shipped in the notebooks repo runs sd.datasets.blobs() (in-memory, no download). Heavier tutorials (Visium, Xenium, MERFISH) will fetch via squidpy.datasets.* when contributors execute them locally — the docs build only renders pre-committed outputs.
Decouples notebook freshness from lib release cycle. The notebooks repo's execute.yaml workflow re-executes every notebook weekly (and on PR) against the latest spatialdata-plot release, catching silent regressions via nbdime diff without blocking lib PRs.
Lib repo stays light. No 1+ MB executed notebooks in the lib's git history; all notebook content lives in the dedicated repo where it can grow.

Mounts scverse/spatialdata-plot-notebooks at docs/notebooks/ and renders it into the docs as a Gallery section, following the scverse convention used by anndata, spatialdata, scvi-tools, and squidpy. Notebooks are pre-executed by humans and committed with outputs in the notebooks repo; this docs build performs no execution. RTD pulls the submodule on each build (submodules.include = all). A new `docs` job in build.yaml runs the docs build on every PR with submodules checked out, gating sphinx warnings (-W) before merge. conf.py exclude_patterns: drop stale `tutorials/notebooks/...` entries (directory was never created), exclude submodule meta-files (README, CONTRIBUTING, LICENSE, .github, pyproject.toml) so they don't trigger toctree warnings. Closes the gallery scope from #463; supersedes the sphinx-gallery approach proposed in #590.

codecov-commenter · 2026-05-11T15:05:09Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.07%. Comparing base (e5c54fd) to head (75de4cc).

Additional details and impacted files

@@ Coverage Diff @@## main #656 +/- ##
==========================================
+ Coverage 77.04% 77.07% +0.03% 
==========================================
Files 11 11 Lines 3280 3280 Branches 774 774 ==========================================
+ Hits 2527 2528 +1 
Misses 454 454 + Partials 299 298 -1

see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Replaces the now-stale "Tutorials with myst-nb" section with concrete instructions for the submodule-based gallery: how to clone with submodules, how to bump the pin, and where to send notebook PRs (the notebooks repo). Adds a heads-up admonition to the "Building the docs locally" section so contributors who cloned without --recurse-submodules know to run `git submodule update --init --recursive` before sphinx-build.

C2 — Render notebooks-repo main, not the pinned SHA .readthedocs.yaml gains a `post_checkout` job that runs `git submodule update --init --remote --recursive` so RTD always renders the latest gallery without requiring a submodule-bump PR here. Mirrored in the docs CI job in build.yaml. Trade-off: docs at older lib tags are no longer bit-for-bit reproducible for the gallery. N1 — Card gallery with thumbnails (matches scverse/spatialdata) Add sphinx-design to doc deps and to the extension list. Rewrite gallery.md to use {grid}/{grid-item-card} with an :img-top: thumbnail. Thumbnail PNG (getting_started.png) committed under docs/_static/gallery. N6 — README points at the gallery New `link-gallery` link target alongside the existing API reference; existing spatialdata-notebooks link reframed as a "broader analyses" pointer. Fixes the "Visiualizations" typo while there.

timtreis · 2026-05-11T14:55:51Z

Inspired by #590 by user asarigun

Summary

Mounts scverse/spatialdata-plot-notebooks at docs/notebooks/ as a git submodule and renders it into the docs as a new Gallery section. Follows the scverse convention used by anndata, spatialdata, scvi-tools, and squidpy (pre-rendered notebooks via myst-nb, nb_execution_mode = "off").

This supersedes the sphinx-gallery approach proposed in #590 — see "Why this approach" below — and addresses the missing-gallery gap identified in #463.

Changes

File	Change
`.gitmodules`	New submodule `docs/notebooks` → `scverse/spatialdata-plot-notebooks` (branch `main`).
`docs/gallery.md`	New gallery landing page with toctree pointing at the submodule's `tutorials/index` and `examples/index`.
`docs/index.md`	Add `gallery.md` to the top-level toctree.
`docs/conf.py`	`exclude_patterns`: drop stale `tutorials/notebooks/...` entries (dir was never created); exclude submodule meta-files (README, CONTRIBUTING, LICENSE, .github, pyproject.toml) so they don't trigger toctree warnings.
`.readthedocs.yaml`	`submodules: include: all` so RTD pulls the notebooks repo on each build.
`.github/workflows/build.yaml`	New `docs` job that builds docs on every PR with submodules checked out — first time docs builds are PR-gated.

No new dependencies. The notebooks repo's pyproject.toml carries squidpy and other heavy tutorial deps; this repo's doc group is unchanged.

Why this approach

Matches every scverse neighbor. anndata, spatialdata, scvi-tools, squidpy all use the same submodule-to-*-notebooks-repo pattern with nb_execution_mode = "off". Sphinx-gallery is unused across scverse.
Zero network and zero execution at lib doc-build time. The getting_started.ipynb already shipped in the notebooks repo runs sd.datasets.blobs() (in-memory, no download). Heavier tutorials (Visium, Xenium, MERFISH) will fetch via squidpy.datasets.* when contributors execute them locally — the docs build only renders pre-committed outputs.
Decouples notebook freshness from lib release cycle. The notebooks repo's execute.yaml workflow re-executes every notebook weekly (and on PR) against the latest spatialdata-plot release, catching silent regressions via nbdime diff without blocking lib PRs.
Lib repo stays light. No 1+ MB executed notebooks in the lib's git history; all notebook content lives in the dedicated repo where it can grow.

Mounts scverse/spatialdata-plot-notebooks at docs/notebooks/ and renders it into the docs as a Gallery section, following the scverse convention used by anndata, spatialdata, scvi-tools, and squidpy. Notebooks are pre-executed by humans and committed with outputs in the notebooks repo; this docs build performs no execution. RTD pulls the submodule on each build (submodules.include = all). A new `docs` job in build.yaml runs the docs build on every PR with submodules checked out, gating sphinx warnings (-W) before merge. conf.py exclude_patterns: drop stale `tutorials/notebooks/...` entries (directory was never created), exclude submodule meta-files (README, CONTRIBUTING, LICENSE, .github, pyproject.toml) so they don't trigger toctree warnings. Closes the gallery scope from #463; supersedes the sphinx-gallery approach proposed in #590.

codecov-commenter · 2026-05-11T15:05:09Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.07%. Comparing base (e5c54fd) to head (75de4cc).

Additional details and impacted files

@@ Coverage Diff @@## main #656 +/- ##
==========================================
+ Coverage 77.04% 77.07% +0.03% 
==========================================
Files 11 11 Lines 3280 3280 Branches 774 774 ==========================================
+ Hits 2527 2528 +1 
Misses 454 454 + Partials 299 298 -1

see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Replaces the now-stale "Tutorials with myst-nb" section with concrete instructions for the submodule-based gallery: how to clone with submodules, how to bump the pin, and where to send notebook PRs (the notebooks repo). Adds a heads-up admonition to the "Building the docs locally" section so contributors who cloned without --recurse-submodules know to run `git submodule update --init --recursive` before sphinx-build.

C2 — Render notebooks-repo main, not the pinned SHA .readthedocs.yaml gains a `post_checkout` job that runs `git submodule update --init --remote --recursive` so RTD always renders the latest gallery without requiring a submodule-bump PR here. Mirrored in the docs CI job in build.yaml. Trade-off: docs at older lib tags are no longer bit-for-bit reproducible for the gallery. N1 — Card gallery with thumbnails (matches scverse/spatialdata) Add sphinx-design to doc deps and to the extension list. Rewrite gallery.md to use {grid}/{grid-item-card} with an :img-top: thumbnail. Thumbnail PNG (getting_started.png) committed under docs/_static/gallery. N6 — README points at the gallery New `link-gallery` link target alongside the existing API reference; existing spatialdata-notebooks link reframed as a "broader analyses" pointer. Fixes the "Visiualizations" typo while there.

timtreis · 2026-05-11T14:55:51Z

Inspired by #590 by user asarigun

Summary

Mounts scverse/spatialdata-plot-notebooks at docs/notebooks/ as a git submodule and renders it into the docs as a new Gallery section. Follows the scverse convention used by anndata, spatialdata, scvi-tools, and squidpy (pre-rendered notebooks via myst-nb, nb_execution_mode = "off").

This supersedes the sphinx-gallery approach proposed in #590 — see "Why this approach" below — and addresses the missing-gallery gap identified in #463.

Changes

File	Change
`.gitmodules`	New submodule `docs/notebooks` → `scverse/spatialdata-plot-notebooks` (branch `main`).
`docs/gallery.md`	New gallery landing page with toctree pointing at the submodule's `tutorials/index` and `examples/index`.
`docs/index.md`	Add `gallery.md` to the top-level toctree.
`docs/conf.py`	`exclude_patterns`: drop stale `tutorials/notebooks/...` entries (dir was never created); exclude submodule meta-files (README, CONTRIBUTING, LICENSE, .github, pyproject.toml) so they don't trigger toctree warnings.
`.readthedocs.yaml`	`submodules: include: all` so RTD pulls the notebooks repo on each build.
`.github/workflows/build.yaml`	New `docs` job that builds docs on every PR with submodules checked out — first time docs builds are PR-gated.

No new dependencies. The notebooks repo's pyproject.toml carries squidpy and other heavy tutorial deps; this repo's doc group is unchanged.

Why this approach

Matches every scverse neighbor. anndata, spatialdata, scvi-tools, squidpy all use the same submodule-to-*-notebooks-repo pattern with nb_execution_mode = "off". Sphinx-gallery is unused across scverse.
Zero network and zero execution at lib doc-build time. The getting_started.ipynb already shipped in the notebooks repo runs sd.datasets.blobs() (in-memory, no download). Heavier tutorials (Visium, Xenium, MERFISH) will fetch via squidpy.datasets.* when contributors execute them locally — the docs build only renders pre-committed outputs.
Decouples notebook freshness from lib release cycle. The notebooks repo's execute.yaml workflow re-executes every notebook weekly (and on PR) against the latest spatialdata-plot release, catching silent regressions via nbdime diff without blocking lib PRs.
Lib repo stays light. No 1+ MB executed notebooks in the lib's git history; all notebook content lives in the dedicated repo where it can grow.

Mounts scverse/spatialdata-plot-notebooks at docs/notebooks/ and renders it into the docs as a Gallery section, following the scverse convention used by anndata, spatialdata, scvi-tools, and squidpy. Notebooks are pre-executed by humans and committed with outputs in the notebooks repo; this docs build performs no execution. RTD pulls the submodule on each build (submodules.include = all). A new `docs` job in build.yaml runs the docs build on every PR with submodules checked out, gating sphinx warnings (-W) before merge. conf.py exclude_patterns: drop stale `tutorials/notebooks/...` entries (directory was never created), exclude submodule meta-files (README, CONTRIBUTING, LICENSE, .github, pyproject.toml) so they don't trigger toctree warnings. Closes the gallery scope from #463; supersedes the sphinx-gallery approach proposed in #590.

codecov-commenter · 2026-05-11T15:05:09Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.07%. Comparing base (e5c54fd) to head (75de4cc).

Additional details and impacted files

@@ Coverage Diff @@## main #656 +/- ##
==========================================
+ Coverage 77.04% 77.07% +0.03% 
==========================================
Files 11 11 Lines 3280 3280 Branches 774 774 ==========================================
+ Hits 2527 2528 +1 
Misses 454 454 + Partials 299 298 -1

see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Replaces the now-stale "Tutorials with myst-nb" section with concrete instructions for the submodule-based gallery: how to clone with submodules, how to bump the pin, and where to send notebook PRs (the notebooks repo). Adds a heads-up admonition to the "Building the docs locally" section so contributors who cloned without --recurse-submodules know to run `git submodule update --init --recursive` before sphinx-build.

C2 — Render notebooks-repo main, not the pinned SHA .readthedocs.yaml gains a `post_checkout` job that runs `git submodule update --init --remote --recursive` so RTD always renders the latest gallery without requiring a submodule-bump PR here. Mirrored in the docs CI job in build.yaml. Trade-off: docs at older lib tags are no longer bit-for-bit reproducible for the gallery. N1 — Card gallery with thumbnails (matches scverse/spatialdata) Add sphinx-design to doc deps and to the extension list. Rewrite gallery.md to use {grid}/{grid-item-card} with an :img-top: thumbnail. Thumbnail PNG (getting_started.png) committed under docs/_static/gallery. N6 — README points at the gallery New `link-gallery` link target alongside the existing API reference; existing spatialdata-notebooks link reframed as a "broader analyses" pointer. Fixes the "Visiualizations" typo while there.

timtreis · 2026-05-11T14:55:51Z

Inspired by #590 by user asarigun

Summary

Mounts scverse/spatialdata-plot-notebooks at docs/notebooks/ as a git submodule and renders it into the docs as a new Gallery section. Follows the scverse convention used by anndata, spatialdata, scvi-tools, and squidpy (pre-rendered notebooks via myst-nb, nb_execution_mode = "off").

This supersedes the sphinx-gallery approach proposed in #590 — see "Why this approach" below — and addresses the missing-gallery gap identified in #463.

Changes

File	Change
`.gitmodules`	New submodule `docs/notebooks` → `scverse/spatialdata-plot-notebooks` (branch `main`).
`docs/gallery.md`	New gallery landing page with toctree pointing at the submodule's `tutorials/index` and `examples/index`.
`docs/index.md`	Add `gallery.md` to the top-level toctree.
`docs/conf.py`	`exclude_patterns`: drop stale `tutorials/notebooks/...` entries (dir was never created); exclude submodule meta-files (README, CONTRIBUTING, LICENSE, .github, pyproject.toml) so they don't trigger toctree warnings.
`.readthedocs.yaml`	`submodules: include: all` so RTD pulls the notebooks repo on each build.
`.github/workflows/build.yaml`	New `docs` job that builds docs on every PR with submodules checked out — first time docs builds are PR-gated.

No new dependencies. The notebooks repo's pyproject.toml carries squidpy and other heavy tutorial deps; this repo's doc group is unchanged.

Why this approach

Matches every scverse neighbor. anndata, spatialdata, scvi-tools, squidpy all use the same submodule-to-*-notebooks-repo pattern with nb_execution_mode = "off". Sphinx-gallery is unused across scverse.
Zero network and zero execution at lib doc-build time. The getting_started.ipynb already shipped in the notebooks repo runs sd.datasets.blobs() (in-memory, no download). Heavier tutorials (Visium, Xenium, MERFISH) will fetch via squidpy.datasets.* when contributors execute them locally — the docs build only renders pre-committed outputs.
Decouples notebook freshness from lib release cycle. The notebooks repo's execute.yaml workflow re-executes every notebook weekly (and on PR) against the latest spatialdata-plot release, catching silent regressions via nbdime diff without blocking lib PRs.
Lib repo stays light. No 1+ MB executed notebooks in the lib's git history; all notebook content lives in the dedicated repo where it can grow.

Mounts scverse/spatialdata-plot-notebooks at docs/notebooks/ and renders it into the docs as a Gallery section, following the scverse convention used by anndata, spatialdata, scvi-tools, and squidpy. Notebooks are pre-executed by humans and committed with outputs in the notebooks repo; this docs build performs no execution. RTD pulls the submodule on each build (submodules.include = all). A new `docs` job in build.yaml runs the docs build on every PR with submodules checked out, gating sphinx warnings (-W) before merge. conf.py exclude_patterns: drop stale `tutorials/notebooks/...` entries (directory was never created), exclude submodule meta-files (README, CONTRIBUTING, LICENSE, .github, pyproject.toml) so they don't trigger toctree warnings. Closes the gallery scope from #463; supersedes the sphinx-gallery approach proposed in #590.

codecov-commenter · 2026-05-11T15:05:09Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.07%. Comparing base (e5c54fd) to head (75de4cc).

Additional details and impacted files

@@ Coverage Diff @@## main #656 +/- ##
==========================================
+ Coverage 77.04% 77.07% +0.03% 
==========================================
Files 11 11 Lines 3280 3280 Branches 774 774 ==========================================
+ Hits 2527 2528 +1 
Misses 454 454 + Partials 299 298 -1

see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Replaces the now-stale "Tutorials with myst-nb" section with concrete instructions for the submodule-based gallery: how to clone with submodules, how to bump the pin, and where to send notebook PRs (the notebooks repo). Adds a heads-up admonition to the "Building the docs locally" section so contributors who cloned without --recurse-submodules know to run `git submodule update --init --recursive` before sphinx-build.

C2 — Render notebooks-repo main, not the pinned SHA .readthedocs.yaml gains a `post_checkout` job that runs `git submodule update --init --remote --recursive` so RTD always renders the latest gallery without requiring a submodule-bump PR here. Mirrored in the docs CI job in build.yaml. Trade-off: docs at older lib tags are no longer bit-for-bit reproducible for the gallery. N1 — Card gallery with thumbnails (matches scverse/spatialdata) Add sphinx-design to doc deps and to the extension list. Rewrite gallery.md to use {grid}/{grid-item-card} with an :img-top: thumbnail. Thumbnail PNG (getting_started.png) committed under docs/_static/gallery. N6 — README points at the gallery New `link-gallery` link target alongside the existing API reference; existing spatialdata-notebooks link reframed as a "broader analyses" pointer. Fixes the "Visiualizations" typo while there.

timtreis added 3 commits May 11, 2026 17:06

Bump notebooks submodule (lint fix in spatialdata-plot-notebooks)
e24d7a2

timtreis merged commit 6687b87 into mainMay 11, 2026
8 of 9 checks passed