Interactive maps (#44)

`stackstac.show` and `stackstac.add_to_map` display Dask-backed DataArrays on ipyleaflet maps.

Other changes:
* Exposed some handy spatial and miscellaneous operations in the public API (`reproject_array`, `xyztile_of_array`, etc.)
* Exposed `stackstac.mosaic`! Closes #1.
* Reorganized docs to have an examples subsection and base API reference page
* Added visualization notebook from my webinar

.readthedocs.yml

@@ -10,4 +10,5 @@ python:
     - method: pip
       path: .
       extra_requirements:
-        - docs
+        - docs
+        - viz

docs/.gitignore

@@ -1,2 +1,3 @@
 _build/*
-api/internal/*.rst
+api/internal/*.rst
+api/main/*.rst

docs/api/main.rst

@@ -1,6 +1,49 @@
 API reference
 -------------
 
-There's only one function:
+.. currentmodule:: stackstac
 
-.. autofunction:: stackstac.stack
+Core
+~~~~
+
+This is what it's all about:
+
+.. autosummary::
+    :toctree: main
+    :nosignatures:
+
+    stack
+
+Visualization
+~~~~~~~~~~~~~
+
+Easily render your data on an :doc:`ipyleaflet <ipyleaflet:index>` map. Requires installing ``'stackstac[viz]'``, and running with a :doc:`dask distributed <distributed:index>` cluster.
+
+As you pan around the map, the part of the array that's in view is computed on the fly by dask.
+
+**Warning**: zooming in and out will *not* load underlying data at different resolutions. Assets will be loaded at whatever resolution you initially got from `~.stack`. If your array is large and high-resolution, zooming out could trigger very slow (and expensive) computations.
+
+
+.. autosummary::
+    :toctree: main
+    :nosignatures:
+
+    show
+    add_to_map
+
+Operations
+~~~~~~~~~~
+
+Utilities to work with geospatial DataArrays produced by stackstac.
+
+**Warning**: these functions may be reorganized in the near future.
+
+.. autosummary::
+    :toctree: main
+    :nosignatures:
+
+    mosaic
+    reproject_array
+    xyztile_of_array
+    array_bounds
+    array_epsg

docs/conf.py

@@ -76,7 +76,6 @@
 # a list of builtin themes.
 #
 html_theme = "insipid"
-
 html_theme_options = {
     "globaltoc_maxdepth": -1,
 }
@@ -92,12 +91,16 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+# html_static_path = ["_static"]
 
 intersphinx_mapping = {
     "rasterio": ("https://rasterio.readthedocs.io/en/latest/", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
     "pystac": ("https://pystac.readthedocs.io/en/latest/", None),
     "xarray": ("http://xarray.pydata.org/en/stable/", None),
     "dask": ("https://docs.dask.org/en/latest/", None),
+    "distributed": ("https://distributed.dask.org/en/latest/", None),
+    "matplotlib": ("https://matplotlib.org/stable", None),
+    "ipyleaflet": ("https://ipyleaflet.readthedocs.io/en/latest/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/reference/", None),
 }

docs/index.rst

@@ -22,7 +22,7 @@ Installation
 
 ``stackstac`` is available on pip::
 
-   pip install stackstac
+   pip install 'stackstac[viz]'
 
 Its main dependencies are rasterio, pyproj, dask, and xarray, all of which should pose no problems to install—no need to build GDAL from source here.
 

examples/index.rst

@@ -7,3 +7,4 @@ More examples
 
     cluster
     gif
+    show