diff --git a/docs/source/getting_started/examples_and_data.rst b/docs/source/getting_started/examples_and_data.rst new file mode 100644 index 000000000..dedeafb3e --- /dev/null +++ b/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 ` 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 `, 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. diff --git a/docs/source/getting_started/index.rst b/docs/source/getting_started/index.rst index bd115e528..312607b43 100644 --- a/docs/source/getting_started/index.rst +++ b/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 ` has worked examples +for every module, and the :doc:`API reference ` +documents each function. + .. toctree:: :maxdepth: 2 + :hidden: why_xarray_spatial installation quickstart + examples_and_data