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

docs/source/getting_started/examples_and_data.rst

@@ -0,0 +1,72 @@
+..  _getting_started.examples_and_data:
+
+******************
+Examples and data
+******************
+
+The quickstart runs on synthetic terrain and needs no downloads. The
+example notebooks are different: they work on real rasters and vector
+files that ship separately. The ``xrspatial`` command-line tool fetches
+both.
+
+The command-line tool
+=====================
+
+Installing the package puts an ``xrspatial`` command on your ``PATH``.
+Run it inside the same environment where you installed the library. Three
+subcommands download the starter material:
+
+.. code-block:: bash
+
+   xrspatial examples         # notebooks and the data they use
+   xrspatial copy-examples    # notebooks only
+   xrspatial fetch-data       # data only
+
+Each one writes into a folder named ``xrspatial-examples`` in your
+current directory. A fourth subcommand, ``xrspatial clean-data``,
+removes downloaded data files.
+
+The command list and per-command options are available with ``--help``:
+
+.. code-block:: bash
+
+   xrspatial --help
+   xrspatial examples --help
+
+If ``xrspatial`` reports a missing command, install the CLI helper with
+``pip install pyct``.
+
+Getting started with the examples
+=================================
+
+Download everything and open the notebooks:
+
+.. code-block:: bash
+
+   xrspatial examples
+   cd xrspatial-examples
+   jupyter notebook
+
+Notebooks live under ``user_guide/`` and cover surface analysis,
+proximity, classification, remote sensing, and the rest of the modules.
+Downloaded datasets land in ``xrspatial-examples/data/``. The same
+notebooks are rendered in the :doc:`user guide </user_guide/index>` if
+you would rather read than run.
+
+Re-running a download overwrites nothing by default. Pass ``--force`` to
+replace files that already exist, or ``--path`` to write somewhere other
+than the current directory:
+
+.. code-block:: bash
+
+   xrspatial examples --path ~/xrspatial-demo --force
+
+Using your own data
+===================
+
+You do not need the example data to use the library. Any 2D
+``xr.DataArray`` works as input, whether you build it yourself, read it
+with :doc:`open_geotiff </reference/geotiff>`, or get it from another
+library. The :doc:`quickstart` shows the no-download path end to end, and
+:doc:`/reference/geotiff` covers reading local files and ``http(s)`` /
+``s3`` / ``gs`` / ``az`` URLs.

docs/source/getting_started/index.rst

@@ -4,9 +4,26 @@
 Getting started
 ***************
 
+New to ``xarray-spatial``? Start here.
+
+* :doc:`why_xarray_spatial` -- what the library does and how it differs
+  from GDAL-based tools.
+* :doc:`installation` -- Python and platform requirements, environment
+  setup, and the optional dependency extras.
+* :doc:`quickstart` -- a runnable first analysis on synthetic terrain,
+  with no data download.
+* :doc:`examples_and_data` -- the ``xrspatial`` command-line tool for
+  downloading the example notebooks and sample datasets.
+
+From there, the :doc:`user guide </user_guide/index>` has worked examples
+for every module, and the :doc:`API reference </reference/index>`
+documents each function.
+
 .. toctree::
    :maxdepth: 2
+   :hidden:
 
    why_xarray_spatial
    installation
    quickstart
+   examples_and_data