Add a why-xarray-spatial page; retire raster_huh#3284
Merged
Conversation
brendancol
commented
Jun 12, 2026
brendancol
left a comment
Contributor
Author
There was a problem hiding this comment.
PR Review: Add a why-xarray-spatial page; retire raster_huh
Blockers
None.
Suggestions
- why_xarray_spatial.rst ("What xarray-spatial is"): "Every function takes an xr.DataArray and returns an xr.DataArray" overclaims. polygonize returns vector geometries, rasterize consumes them, and the pathfinding functions take point arguments. Describe it as the core pattern rather than a universal rule.
Nits
None.
What looks good
- The raster_huh paragraphs move unchanged, and the GDAL note keeps its original tone while the final paragraph now matches the README's current no-GDAL/no-GEOS claim instead of the old "algorithms only" wording.
- Toctree lands at the intended final order (motivation, setup, doing) and no references to raster_huh remain.
- Backend story is accurate: dispatch is by input array type, and the tier caveat links the stability policy instead of restating it.
Checklist
- Code-level items: not applicable (docs-only)
- Docs build: clean, pre-existing warnings only
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Refs #3249 (part 5 of 6).
raster_huh.rst was two paragraphs, and the GDAL note lost its home when usage.rst was replaced (#3258). This page gives both a permanent spot and adds the positioning the docs never had:
Toctree order becomes why_xarray_spatial, installation, quickstart: motivation, then setup, then doing.
Test plan:
sphinx-build -b htmlclean, pre-existing warnings only