Merge pull request #617 from opendatacube/doc_updates

Documentation updates

Author: pindge

docs/configuration.rst

@@ -36,8 +36,8 @@ All examples in this documentation will always be presented in Python syntax.  J
 note that there are some important differences:
 
 1. JSON string literals must always be delimited with double quotes - so no Python-style single quote strings!
-2. JSON boolean literals are all lowercase (`true`, `false`) and Python boolean literals are title case (e.g.
-   `True`, `False`)
+2. JSON boolean literals are all lowercase (``true``, ``false``) and Python boolean literals are title case (e.g.
+   ``True``, ``False``)
 3. JSON does not allow commas after the last element of lists and objects (dictionaries in Python terms).
 4. JSON does not support comments of any kind.
 
@@ -332,7 +332,7 @@ Internationalisation/Translation of Metadata
 ++++++++++++++++++++++++++++++++++++++++++++
 
 Once you have extracted your metadata into a single file, separate from the main body of configuration,
-as described `above<#metadata-separation>`_, generate a translation catalog for every language you want
+as described `above <#metadata-separation>`_, generate a translation catalog for every language you want
 translations for - including the "native" language that your messages file is already in:
 
 ::
@@ -365,13 +365,17 @@ Once the translations have been placed in translations directory, they must be c
 
 This creates the following machine-readable message (.mo) files:
 
+::
+
    /config/translations/en/LC_MESSAGES/my_ows_project.mo
    /config/translations/de/LC_MESSAGES/my_ows_project.mo
    /config/translations/fr/LC_MESSAGES/my_ows_project.mo
    /config/translations/sw/LC_MESSAGES/my_ows_project.mo
 
-You can now update the `global section of your OWS Configuration<>`_ and restart the web service and
-you are serving multi-lingually!  (Adjust your client's "Accept-Languages" header to test.)
+You can now update the
+`global section of your OWS Configuration <https://datacube-ows.readthedocs.io/en/latest/cfg_global.html#metadata-separation-and-internationalisation>`_
+section and restart the web service and
+you are serving multi-lingually!  (Adjust your client's "Accept-Language" header to test.)
 
 General Config Structure
 ------------------------

docs/style_howto_color_ramp.rst

@@ -64,15 +64,16 @@ so ``ocean_r`` is the reverse - from white through darker blues to dark green.
 So now we get white in the negative and zero areas, with positive areas
 getting darkening blues with close to 1.0 being dark green.
 
+This configuration also demonstrates another method for defining the index - with
+a simple expression language instead of referencing an explicit python function.
+The expression language includes band names and literal numbers, as well as simple
+arthimetic operators like `+ - / *` and parentheses for precedence.
+
 ::
 
     ndvi_unidirection_cfg = {
-        "index_function": {
-            "function": "datacube_ows.band_utils.norm_diff",
-            "mapped_bands": True,
-            "kwargs": {"band1": "nir", "band2": "red"},
-        },
-        "mpl_ramp": "ocean_r",
+        "index_expression": "(nir-red)/(nir+red)",
+        "mpl_ramp": "ocean_r",    #  ocean_r is the "ocean" ramp, reversed.
         "range": [0.0, 1.0]
     }
 

docs/style_howto_components.rst

@@ -105,7 +105,12 @@ If we wanted a greyscale image of a single band (say red), you could do this:
 Example: Mixing bands
 +++++++++++++++++++++
 
-What if we want to mix more than one band to make each channel? Here we average all three visible bands
+What if we want to mix more than one band to make each channel?  We can simply add more bands to the
+various colour channel dictionaries, with multiplying factors.  Normally we ensure that the multiplying
+factors for each channel sum to 1.0, so the result is a (possibly weighted) average of the input bands,
+but this is not enforced.
+
+Here we average all three visible bands
 into the red channel, put near infra-red in the green channel and average the two shortwave infrared
 bands to make the blue channel:
 
@@ -114,16 +119,22 @@ bands to make the blue channel:
     all_bands_cfg = {
         "components": {
             "red": {
-             "red": 0.333,
-             "green": 0.333,
-             "blue": 0.333,
+                # Weighting factors should sum to (close to) 1.0
+                # 0.333 + 0.333 + 0.333 = 0.999 ~ 1.0
+                "red": 0.333,
+                "green": 0.333,
+                "blue": 0.333,
             },
             "green": {
-             "nir": 1.0
+                # Weighting factors should sum to (close to) 1.0
+                # So use 1.0 for a single band.
+                "nir": 1.0
             },
             "blue": {
-             "swir1": 0.5,
-             "swir2": 0.5,
+                # Weighting factors should sum to (close to) 1.0
+                # 0.5 + 0.5 = 1.0
+                "swir1": 0.5,
+                "swir2": 0.5,
             },
         },
         "scale_range": (50, 3000),

docs/style_howto_components_nonlinear.rst

@@ -46,7 +46,7 @@ For example, given this function, containing a simple unscaled implementation of
 
     def ndvi(data):
         # Returns data in range (-1, 1)
-        return (data["nir"] - data["red"]) / (data["nir"] + data["red")
+        return (data["nir"] - data["red"]) / (data["nir"] + data["red"])
 
 
 Using ``"green": ndvi,`` in the components dictionary would sort of work, but would
@@ -62,7 +62,7 @@ not what we want. We can add scaling like this:
         # Scale to [-1.0 - 1.0] to [0 - 255]
         scaled = ((unscaled + 1.0) * 255/2).clip(0, 255)
 
-        returned scaled
+        return scaled
 
     r_ndvi_b_fullrange_cfg = {
         "components": {
@@ -103,7 +103,6 @@ for a more streamlined solution to scaling:
 Example: red-ndvi-blue (half scale)
 +++++++++++++++++++++++++++++++++++
 
-
 ::
 
     from datacube_ows.styles.api import scalable

docs/style_howto_transparency.rst

@@ -91,9 +91,9 @@ vegetation (npv)" band mapped to blue.
         "components": {
             "red": {"bs": 1.0},
             "green": {"pv": 1.0},
-            "blue": {"npv": 1.0}},
+            "blue": {"npv": 1.0}
+        },
         "scale_range": [0.0, 100.0],
-        }
     }
 
 .. image:: https://user-images.githubusercontent.com/4548530/113671209-66c2d600-96f9-11eb-8354-43a64ec1d134.png
@@ -117,9 +117,9 @@ keep in the image - pixels that fail any of the pq_mask rules will be transparen
         "components": {
             "red": {"bs": 1.0},
             "green": {"pv": 1.0},
-            "blue": {"npv": 1.0}},
-        "scale_range": [0.0, 100.0],
+            "blue": {"npv": 1.0}
         },
+        "scale_range": [0.0, 100.0],
         "pq_masks": [
             # Pixels must match all flags to remain visible.
             {
@@ -303,6 +303,7 @@ transparent with values between 0 and 0.5 shown partially transparent:
         },
         "scale_range": (50, 3000),
     }
+
 .. image:: https://user-images.githubusercontent.com/4548530/113795937-5d854800-9791-11eb-9a49-25ea8cbced64.png
     :width: 600