Add examples-and-data getting-started page and landing index#3316
Merged
Conversation
brendancol
commented
Jun 14, 2026
brendancol
left a comment
Contributor
Author
There was a problem hiding this comment.
PR Review: Add examples-and-data getting-started page and landing index
This is a docs-only PR (two reStructuredText files), so the correctness, backend-parity, and performance sections of the review template do not apply. I focused on whether the documented commands are accurate and whether the Sphinx cross-references resolve.
Blockers
None.
Suggestions
examples_and_data.rst: "The data they read sits in thedata/folder next to them" matches the pyctfetch-datalayout (its--helpsays datasets are placed inpath/data), but not every example notebook reads from adata/subfolder. If you want to be precise, say the data lands inxrspatial-examples/data/rather than implying every notebook reads from there. Not blocking.
Nits
None.
What looks good
- The CLI surface matches
python -m xrspatial --helpexactly:examples,copy-examples,fetch-data,clean-data, thexrspatial-examplesdownload folder, and the--force/--pathflags. - Every
:doc:cross-reference (user_guide/index,reference/geotiff,reference/index,quickstart,installation) resolves to an existing page. - reST title underlines are the right length.
- The
pip install pyctfallback matches the import guard inxrspatial/__main__.py. - The
index.rstrewrite keeps the toctree (now hidden), so navigation is unchanged while adding a readable landing page.
Checklist
- Algorithm / backend / NaN / dask / benchmark items: not applicable (docs only).
- Cross-references resolve.
- CLI claims verified against the installed command.
sphinx-build -b htmlreads both pages with no new warnings.
brendancol
commented
Jun 14, 2026
brendancol
left a comment
Contributor
Author
There was a problem hiding this comment.
Follow-up review (after c72f839)
The one suggestion from the first pass is addressed: the examples page now states that downloaded datasets land in xrspatial-examples/data/ instead of implying every notebook reads from a data/ subfolder.
No remaining findings. Still docs-only; CLI claims and cross-references re-checked and accurate.
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.
Closes #3249
This is the last of the six getting-started PRs from #3249. The other five already merged (#3251, #3252, #3257, #3258, #3284), leaving the examples/data page and the landing-page rewrite.
getting_started/examples_and_data.rst: documents thexrspatialCLI (examples,copy-examples,fetch-data,clean-data), where downloads land (xrspatial-examples/),--force/--path, and how to bring your own data instead.getting_started/index.rstfrom a bare toctree into a short landing page that orients new users across the four pages and points onward to the user guide and API reference. Addsexamples_and_datato the toctree.Docs only. No code, no public API, no backend behavior changed.
Test plan
python -m xrspatial --help(commands and download folder name).:doc:cross-reference resolves to an existing page.sphinx-build -b htmland confirmed no new warnings for the changed pages.