Reason or Problem
docs/source/getting_started/ is about 70 lines across four pages and parts of it are out of date:
- usage.rst still says xarray-spatial "currently depends on Datashader, but will soon be updated to depend only on xarray and numba". Core install deps have been numpy, numba, scipy, xarray, urllib3, zstandard for a while now; datashader only appears in the
examples extra.
- installation.rst documents 2 of the 10 extras (
plot, vector). Nothing on geotiff, dask, gpu, reproject, optional, the libnvcomp/kvikio runtime caveat, or cloud-storage deps.
- No environment setup guidance and no mention that Python >= 3.12 is required.
- No quickstart that runs end to end, and no mention of the
xrspatial examples / fetch-data download commands.
- No links to the user guide caveats or the stability policy, so a new user can miss the WGS84 / float32 / NaN-nodata assumptions and silently get wrong results.
- Sphinx only builds on Read the Docs; nothing checks that docs build on PRs.
Proposal
Restructure getting_started/ into four pages (why_xarray_spatial, installation, quickstart, examples_and_data) in six small PRs:
- Fix the stale Datashader claim and the hardcoded GitHub example links (usage.rst, installation.rst).
- Add a docs-build CI job that runs sphinx-build on PRs touching docs/.
- Rewrite installation.rst: environment setup (venv / conda / uv), a table covering every extra in setup.cfg, GPU setup notes (cupy/CUDA, libnvcomp + kvikio), cloud storage deps, and an install verification snippet.
- Add quickstart.rst, replacing usage.rst: a generate_terrain-based first example that needs no data download, the .xrs accessor, a GeoTIFF read/write round trip, Dataset support, short dask and GPU pointers, and a link to the caveats page.
- Add why_xarray_spatial.rst, absorbing raster_huh.rst and the GDAL note from usage.rst.
- Add examples_and_data.rst covering the xrspatial CLI download commands, plus a landing-page rewrite for getting_started/index.rst.
Each PR should merge on its own, and every command shown in the docs gets run during review.
Impacts
Docs-only except PR 2, which adds one GitHub Actions workflow. Two pages (raster_huh.html, usage.html) go away and their URLs break; nothing inside the docs links to them. Redirects via sphinx-reredirects came up and got skipped: not worth a new doc dependency for two low-traffic pages.
Reason or Problem
docs/source/getting_started/ is about 70 lines across four pages and parts of it are out of date:
examplesextra.plot,vector). Nothing ongeotiff,dask,gpu,reproject,optional, the libnvcomp/kvikio runtime caveat, or cloud-storage deps.xrspatial examples/fetch-datadownload commands.Proposal
Restructure getting_started/ into four pages (why_xarray_spatial, installation, quickstart, examples_and_data) in six small PRs:
Each PR should merge on its own, and every command shown in the docs gets run during review.
Impacts
Docs-only except PR 2, which adds one GitHub Actions workflow. Two pages (raster_huh.html, usage.html) go away and their URLs break; nothing inside the docs links to them. Redirects via sphinx-reredirects came up and got skipped: not worth a new doc dependency for two low-traffic pages.