From 345fd4b9afef46e6584ebccbd5459ab9ae81a1bf Mon Sep 17 00:00:00 2001 From: Phil Schaf Date: Thu, 12 Nov 2026 15:38:21 +0100 Subject: [PATCH 1/3] style: switch to panache markdown formatting --- .panache.toml | 14 ++++++++++++++ .pre-commit-config.yaml | 4 ++++ README.md | 4 ++-- docs/api.md | 2 ++ docs/contributing.md | 22 +++++----------------- docs/gallery.md | 2 +- docs/index.md | 1 - plans/issue-749.md | 15 ++++++++++----- 8 files changed, 38 insertions(+), 26 deletions(-) create mode 100644 .panache.toml diff --git a/.panache.toml b/.panache.toml new file mode 100644 index 00000000..9dfd77fe --- /dev/null +++ b/.panache.toml @@ -0,0 +1,14 @@ +#:schema https://panache.bz/panache.schema.json +flavor = "myst" + +[format] +wrap = "preserve" +smart-punctuation = "unicode" +tab-stops = "preserve" + +# MyST syntax extensions from `myst_enable_extensions` in `docs/conf.py` +[extensions] +tex-math-dollars = true # amsmath, dollarmath +myst-colon-fence = true # colon_fence +definition-lists = true # deflist +raw-html = true # html_admonition, html_image diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 368303a4..a05b183b 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -11,6 +11,10 @@ repos: hooks: - id: biome-format exclude: ^\.cruft\.json$ # inconsistent indentation with cruft - file never to be modified manually. + - repo: https://github.com/jolars/panache-pre-commit + rev: v3.18.0 + hooks: + - id: panache-format - repo: https://github.com/tox-dev/pyproject-fmt rev: v2.25.3 hooks: diff --git a/README.md b/README.md index 19b508de..070ae96d 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ For more information on the `spatialdata-plot` library, please refer to the [doc ## Installation -You need to have Python 3.12 or newer installed on your system. If you don't have +You need to have Python 3.12 or newer installed on your system. If you don’t have Python installed, we recommend installing [Mambaforge](https://github.com/conda-forge/miniforge#mambaforge). There are several alternative options to install spatialdata-plot: @@ -79,6 +79,6 @@ If you like scverse® and want to support our mission, please consider making a +> diff --git a/docs/api.md b/docs/api.md index 6ad7c002..16c44bbc 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,5 +1,6 @@ # API + ```{toctree} :maxdepth: 1 :caption: API @@ -7,3 +8,4 @@ plotting.rst ``` + diff --git a/docs/contributing.md b/docs/contributing.md index 10317dc9..c023859f 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -12,7 +12,6 @@ the [scientific Python tutorials][], or the [scanpy developer guide][]. [scanpy developer guide]: https://scanpy.scverse.org/page/dev/ :::{tip} The *hatch* project manager - We highly recommend to familiarize yourself with [`hatch`][hatch]. Hatch is a Python project manager that @@ -23,14 +22,13 @@ Hatch is a Python project manager that While the project is setup with `hatch` in mind, it is still possible to use different tools to manage dependencies, such as `uv` or `pip`. - ::: [hatch]: https://hatch.pypa.io/latest/ ## Installing dev dependencies -In addition to the packages needed to _use_ this package, +In addition to the packages needed to *use* this package, you need additional python packages to [run tests](#writing-tests) and [build the documentation](#docs-building). :::::{tab-set} @@ -52,9 +50,9 @@ If you are using VS code, install the [hatch-code][] extension. Additionally, make sure that the `vscode-python-environments` extension is installed (should be by default) and `"python.useEnvironmentsExtension": true` is activated in your `settings.json`. -Next, open the "Python Environment Managers" sidebar. +Next, open the “Python Environment Managers” sidebar. You can do so by opening the command palette (Ctrl+Shift+P) and searching for `Python: Focus on Environment Managers View`. -It will show a collapsible list where you can expand "Hatch" +It will show a collapsible list where you can expand “Hatch” and activate an environment by clicking on the checkmark next to it. As the main development environment, we recommend to use `hatch-test` with the latest supported Python version. @@ -100,8 +98,6 @@ hatch env find hatch-test.py3.14-stable ``` and manually point it to the python binary. - - :::: ::::{tab-item} uv @@ -121,7 +117,6 @@ uv sync --all-extras ``` The `.venv` directory is typically automatically discovered by IDEs such as VS Code. - :::: ::::{tab-item} Pip @@ -138,7 +133,6 @@ pip install -e . --group dev --group test --group doc ``` The `.venv` directory is typically automatically discovered by IDEs such as VS Code. - :::: ::::: @@ -173,7 +167,7 @@ git pull --rebase to integrate the changes into yours. While the [pre-commit.ci][] is useful, we strongly encourage installing and running the checks locally first to understand their usage. -Finally, most editors have an _autoformat on save_ feature. +Finally, most editors have an *autoformat on save* feature. Consider enabling this option for [ruff][ruff-editors] and [biome][biome-editors]. [pre-commit]: https://pre-commit.com/ @@ -204,7 +198,6 @@ hatch test # test with the highest supported Python version # or hatch test --all # test with all supported Python versions ``` - :::: ::::{tab-item} uv @@ -213,7 +206,6 @@ hatch test --all # test with all supported Python versions ```bash uv run pytest ``` - :::: ::::{tab-item} Pip @@ -223,7 +215,6 @@ uv run pytest source .venv/bin/activate pytest ``` - :::: ::::: @@ -260,7 +251,7 @@ Please adhere to [Semantic Versioning][semver], in brief > > Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format. -Once you are done, commit and push your changes and navigate to the "Releases" page of this project on GitHub. +Once you are done, commit and push your changes and navigate to the “Releases” page of this project on GitHub. Specify `vX.X.X` as a tag name and create a release. For more information, see [managing GitHub releases][]. This will automatically create a git tag and trigger a Github workflow that creates a release on [PyPI][]. @@ -319,7 +310,6 @@ please check out [this feature request][issue-render-notebooks] in the `cookiecu hatch run docs:build hatch run docs:open ``` - :::: ::::{tab-item} uv @@ -330,7 +320,6 @@ cd docs uv run sphinx-build -M html . _build -W (xdg-)open _build/html/index.html ``` - :::: ::::{tab-item} Pip @@ -342,6 +331,5 @@ cd docs sphinx-build -M html . _build -W (xdg-)open _build/html/index.html ``` - :::: ::::: diff --git a/docs/gallery.md b/docs/gallery.md index 6372ff0a..e65f8dd1 100644 --- a/docs/gallery.md +++ b/docs/gallery.md @@ -19,7 +19,7 @@ Learn the API on synthetic data. Start with *Getting started*. ## Examples -Apply the API to real datasets you'd actually analyse. +Apply the API to real datasets you’d actually analyse. :::{include} notebooks/examples/index.md :start-after: diff --git a/docs/index.md b/docs/index.md index 4aafabc5..3fb5a349 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,4 @@ ```{include} ../README.md - ``` ```{toctree} diff --git a/plans/issue-749.md b/plans/issue-749.md index 5fcf5c15..d2903af6 100644 --- a/plans/issue-749.md +++ b/plans/issue-749.md @@ -3,7 +3,7 @@ ## Root cause When a SpatialElement carries transformations to **multiple coordinate systems** -(e.g. visium's `""` and `"_downscaled_lowres"` pair), `filter_by_coordinate_system` +(e.g. visium’s `""` and `"_downscaled_lowres"` pair), `filter_by_coordinate_system` cannot strip the extra transformation (upstream spatialdata #176). `show()` then auto-detects **more coordinate systems than the user intended**. When the user passes a single `ax`, `_plan_panels` raises: @@ -31,10 +31,10 @@ dropped (redundant) coordinate systems and pointing to `coordinate_systems=`. If the sets are genuinely distinct (count still `> n_ax`), fall through to the existing, correct `ValueError`. -| File | Change | Rationale | -|------|--------|-----------| -| `src/spatialdata_plot/pl/basic.py` (`_resolve_coordinate_systems`) | After `strict_cs`, dedup redundant CS by element set when `ax` given + auto-detected; warn | Fixes the mismatch only on the path that currently errors → strictly backward compatible | -| `tests/pl/test_show.py` | Regression test: multi-CS element + single `ax` no longer raises; distinct-CS case still raises | Lock behavior | + | File | Change | Rationale | + | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | + | `src/spatialdata_plot/pl/basic.py` (`_resolve_coordinate_systems`) | After `strict_cs`, dedup redundant CS by element set when `ax` given + auto-detected; warn | Fixes the mismatch only on the path that currently errors → strictly backward compatible | + | `tests/pl/test_show.py` | Regression test: multi-CS element + single `ax` no longer raises; distinct-CS case still raises | Lock behavior | Why scope to the `ax`-provided path only: the no-`ax` case currently produces one panel per coordinate system (redundant but not an error). Collapsing that @@ -43,6 +43,7 @@ break the reporter explicitly asked to avoid. The `ax` path currently *errors*, so fixing it breaks nothing that worked before. ## Edge cases + - [ ] 2 CS, same element set, single `ax` → collapse to 1, warn, render (main fix). - [ ] 2 CS, **different** element sets, single `ax` → still raise ValueError (correct; genuinely 2 panels). - [ ] N CS redundant, `ax` is a list of N → counts already match, no change. @@ -52,16 +53,19 @@ so fixing it breaks nothing that worked before. - [ ] Multi-panel `color=[...]` → single CS required already; unaffected. ## Downstream impact + - Public API unchanged (no new/changed kwargs). - Only converts a previously-raised `ValueError` into a successful render + warning. - No baseline image changes expected (new path only exercised by the regression test, which is non-visual). ## Test plan + - [ ] Regression test (non-visual): multi-CS element, `filter_by_coordinate_system`, `render_shapes().show(ax=ax)` → no raise; assert 1 axis used. - [ ] Negative test: 2 CS with different elements + single `ax` → still raises `ValueError`. - [ ] Assert a `UserWarning` is emitted mentioning the dropped CS. ## Risks + - Representative choice is "first in coordinate-system order", which may be the `_downscaled_lowres` variant. Visually identical for a standalone plot (axes autoscale), but a user overlaying multiple `show()` calls on one `ax` should @@ -69,6 +73,7 @@ so fixing it breaks nothing that worked before. - Low risk overall: new code runs only where the code previously raised. ## Alternative (Approach 2 — not recommended) + Deduplicate redundant coordinate systems in auto-detect for **both** `ax` and no-`ax` paths. More internally consistent, but changes existing no-`ax` multi-panel output and possibly visual baselines → backward-incompatible. From dba17dcb26b284ea6cd0e50bf8fedf9bf0ede1f1 Mon Sep 17 00:00:00 2001 From: Phil Schaf Date: Thu, 12 Nov 2026 16:59:12 +0100 Subject: [PATCH 2/3] style: use scverse_doc MyST extensions in panache config --- .panache.toml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.panache.toml b/.panache.toml index 9dfd77fe..cd9509d6 100644 --- a/.panache.toml +++ b/.panache.toml @@ -6,9 +6,9 @@ wrap = "preserve" smart-punctuation = "unicode" tab-stops = "preserve" -# MyST syntax extensions from `myst_enable_extensions` in `docs/conf.py` +# MyST syntax extensions from `scverse_doc.config.MYST_ENABLE_EXTENSIONS` [extensions] -tex-math-dollars = true # amsmath, dollarmath myst-colon-fence = true # colon_fence definition-lists = true # deflist -raw-html = true # html_admonition, html_image +tex-math-dollars = true # dollarmath, amsmath +raw-html = true # html_image, html_admonition From 41a21769cb4caf3d16c2c788c03f9b620756153e Mon Sep 17 00:00:00 2001 From: Phil Schaf Date: Thu, 12 Nov 2026 18:01:52 +0100 Subject: [PATCH 3/3] style: drop unneeded panache ignore comments --- docs/api.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/api.md b/docs/api.md index 16c44bbc..c19d3ee9 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,11 +1,8 @@ # API - ```{toctree} :maxdepth: 1 :caption: API plotting.rst - ``` -