EP-4053/#255 Add basic docs (under cookbook) and CHANGELOG entry

Author: soxofaan

CHANGELOG.md

@@ -12,6 +12,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add `options` argument to `DataCube.atmospheric_correction` ([Open-EO/openeo-python-driver#91](https://github.com/Open-EO/openeo-python-driver/issues/91))
 - Add `atmospheric_correction_options` and `cloud_detection_options` arguments to `DataCube.ard_surface_reflectance` ([Open-EO/openeo-python-driver#91](https://github.com/Open-EO/openeo-python-driver/issues/91))
 - UDP storing: add support for "returns", "categories", "examples" and "links" properties ([#242](https://github.com/Open-EO/openeo-python-client/issues/242))
+- Add `openeo.extra.spectral_indices`: experimental API to easily compute spectral indices (vegetation, water, urban, ...)
+  on a `DataCube`, using the index definitions from [Awesome Spectral Indices](https://awesome-ee-spectral-indices.readthedocs.io/en/latest/)
 
 
 ### Changed

docs/cookbook/index.rst

@@ -8,3 +8,4 @@ OpenEO CookBook
    ard
    sampling
    udp_sharing
+   spectral_indices

docs/cookbook/spectral_indices.rst

@@ -0,0 +1,9 @@
+====================================
+Spectral Indices
+====================================
+
+.. warning::
+    This is a new experimental API, subject to change.
+
+.. automodule:: openeo.extra.spectral_indices
+    :members: list_indices, compute_and_rescale_indices, append_and_rescale_indices, compute_indices, append_indices, compute_index, append_index

openeo/extra/spectral_indices/__init__.py

@@ -1,5 +1,13 @@
 """
-Calculate spectral indices (vegetation indices, water indices, etc.) in one line
+Easily calculate spectral indices (vegetation, water, urban etc.).
+
+Supports the indices defined in the
+`Awesome Spectral Indices <https://awesome-ee-spectral-indices.readthedocs.io/>`_ project
+by `David Montero Loaiza <https://github.com/davemlz>`_.
+
+
+.. versionadded:: 0.9.1
+
 """
 
 from openeo.extra.spectral_indices.spectral_indices import *

openeo/extra/spectral_indices/spectral_indices.py

@@ -144,12 +144,13 @@ def compute_and_rescale_indices(datacube: DataCube, index_dict: dict, append=Fal
                 }
             }
 
-        See `list_indices()` for supported indices.
+        If you don't want to rescale your data, you can fill the input-, index- and output-range with ``None``.
 
-    .. note:: this "rescaled" index version uses an experimental API (e.g. `index_dict` argument) that is subject to change.
+        See `list_indices()` for supported indices.
 
-    If you don't want to rescale your data, you can fill the input-, index- and output range with None.
     :return: the datacube with the indices attached as bands
+
+    .. warning:: this "rescaled" index helper uses an experimental API (e.g. `index_dict` argument) that is subject to change.
     """
     index_specs = load_indices()
 
@@ -185,9 +186,9 @@ def append_and_rescale_indices(datacube: DataCube, index_dict: dict) -> DataCube
 
         See `list_indices()` for supported indices.
 
-    .. note:: this "rescaled" index version uses an experimental API (e.g. `index_dict` argument) that is subject to change.
-
     :return: data cube with appended indices
+
+    .. warning:: this "rescaled" index helper uses an experimental API (e.g. `index_dict` argument) that is subject to change.
     """
     return compute_and_rescale_indices(datacube=datacube, index_dict=index_dict, append=True)
 
@@ -233,6 +234,7 @@ def compute_index(datacube: DataCube, index: str) -> DataCube:
     :param index: name of the index to compute. See `list_indices()` for supported indices.
     :return: data cube containing the index as band
     """
+    # TODO: option to compute the index with `reduce_dimension` instead of `apply_dimension`?
     return compute_indices(datacube=datacube, indices=[index], append=False)