Skip to content

Add examples-and-data getting-started page and landing index#3316

Merged
brendancol merged 2 commits into
mainfrom
issue-3249
Jun 14, 2026
Merged

Add examples-and-data getting-started page and landing index#3316
brendancol merged 2 commits into
mainfrom
issue-3249

Conversation

@brendancol

Copy link
Copy Markdown
Contributor

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.

  • Add getting_started/examples_and_data.rst: documents the xrspatial CLI (examples, copy-examples, fetch-data, clean-data), where downloads land (xrspatial-examples/), --force / --path, and how to bring your own data instead.
  • Rewrite getting_started/index.rst from 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. Adds examples_and_data to the toctree.

Docs only. No code, no public API, no backend behavior changed.

Test plan

  • Verified the CLI surface against python -m xrspatial --help (commands and download folder name).
  • Checked every :doc: cross-reference resolves to an existing page.
  • Built the docs with sphinx-build -b html and confirmed no new warnings for the changed pages.

@github-actions github-actions Bot added the performance PR touches performance-sensitive code label Jun 14, 2026

@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 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 the data/ folder next to them" matches the pyct fetch-data layout (its --help says datasets are placed in path/data), but not every example notebook reads from a data/ subfolder. If you want to be precise, say the data lands in xrspatial-examples/data/ rather than implying every notebook reads from there. Not blocking.

Nits

None.

What looks good

  • The CLI surface matches python -m xrspatial --help exactly: examples, copy-examples, fetch-data, clean-data, the xrspatial-examples download folder, and the --force / --path flags.
  • 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 pyct fallback matches the import guard in xrspatial/__main__.py.
  • The index.rst rewrite 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 html reads both pages with no new warnings.

@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.

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.

@brendancol brendancol merged commit ef1a0ff into main Jun 14, 2026
9 checks passed
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.

Overhaul the getting-started docs: environment setup, optional deps, runnable quickstart

1 participant