Skip to content

Add a why-xarray-spatial page; retire raster_huh#3284

Merged
brendancol merged 1 commit into
mainfrom
issue-3249-pr5
Jun 12, 2026
Merged

Add a why-xarray-spatial page; retire raster_huh#3284
brendancol merged 1 commit into
mainfrom
issue-3249-pr5

Conversation

@brendancol

Copy link
Copy Markdown
Contributor

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:

  • "What is a raster?": the raster_huh paragraphs, unchanged.
  • "What xarray-spatial is": the 150+ function summary and the four-backend dispatch story, with pointers to the README feature matrix and the stability policy for per-backend tiers.
  • "No GDAL, no GEOS": the GDAL note from the old usage page, updated to present tense. The old text said compute was pure Python but was written when I/O still went through other libraries; it now matches the README's current claim that raster I/O, reprojection, and codecs are also GDAL-free.
  • "How it fits the ecosystem": any 2D DataArray works as input (rioxarray output included), plus the Datashader origin sentence.

Toctree order becomes why_xarray_spatial, installation, quickstart: motivation, then setup, then doing.

Test plan:

  • sphinx-build -b html clean, pre-existing warnings only
  • no remaining references to raster_huh anywhere in docs/

@brendancol brendancol left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@github-actions github-actions Bot added the performance PR touches performance-sensitive code label Jun 12, 2026
@brendancol brendancol merged commit a74efc2 into main Jun 12, 2026
9 checks passed
@brendancol brendancol deleted the issue-3249-pr5 branch June 25, 2026 13:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

performance PR touches performance-sensitive code

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant