Lots of documentation tidying

.dockerignore

@@ -1,9 +1,10 @@
 datacube_wms/wms_cfg_local.py
-.pytest_cache
-*/__pycache__
+**/.pytest_cache
+**/__pycache__
+.hypothesis
 
 venv
 .venv
 
-.pixi
+**/.pixi
 .git

Dockerfile.micromamba

@@ -1,7 +1,11 @@
 FROM mambaorg/micromamba:1.5.8
 COPY --chown=$MAMBA_USER:$MAMBA_USER env.micromamba.yaml /tmp/env.yaml
 RUN --mount=type=cache,target=/opt/conda/pkgs micromamba install -y -n base -f /tmp/env.yaml && \
-    micromamba clean --all --yes
+    micromamba clean --all --yes --force-pkgs-dirs && \
+#    find /home/mambauser/.mamba/pkgs -type d \( -name test -o -name tests \) -print0 | xargs -0 rm -rf && \
+    find /opt/conda/lib -type d \( -name test -o -name tests \) -print0 | xargs -0 rm -rf && \
+    rm -rf /opt/conda/lib/libpython3* /opt/conda/include /opt/conda/share/{gir-1.0,poppler,man}
+# TODO: pieces of botocore (98Mb) and scipy (72Mb) can likely be removed
 
 ARG MAMBA_DOCKERFILE_ACTIVATE=1  # (otherwise python will not be found)
 

README.rst

@@ -1,6 +1,6 @@
-============
+==========================
 Datacube Open Web Services
-============
+==========================
 
 .. image:: https://github.com/opendatacube/datacube-ows/actions/workflows/lint.yml/badge.svg
    :target: https://github.com/opendatacube/datacube-ows/actions/workflows/lint.yml
@@ -53,7 +53,7 @@ Community
 
 This project welcomes community participation.
 
-`Join the ODC Discord <http://slack.opendatacube.org>`__ if you need help
+`Join the ODC Discord <https://discord.com/invite/4hhBQVas5U>`__ if you need help
 setting up or using this project, or the Open Data Cube more generally.
 Conversation about datacube-ows is mostly concentrated in the Discord
 channel ``#wms``.
@@ -197,11 +197,11 @@ The following instructions are for installing on a clean Linux system.
 
 * Create a configuration file for your service, and all data products you wish to publish in
   it.
-  `Detailed documentation of the configuration format can be found here.<https://datacube-ows.readthedocs.io/en/latest/configuration.html>`_
+  `Detailed documentation of the configuration format can be found here. <https://datacube-ows.readthedocs.io/en/latest/configuration.html>`_
 
 * Set environment variables as required.
   Environment variables that directly or indirectly affect the running of OWS
-  are `documented here<https://datacube-ows.readthedocs.io/en/latest/environment_variables.html>`_.
+  are `documented here <https://datacube-ows.readthedocs.io/en/latest/environment_variables.html>`_.
 
 
 * Run ``datacube-ows-update`` (in the Datacube virtual environment).

docs/cfg_colourmap_styles.rst

@@ -7,7 +7,7 @@ OWS Configuration - Colourmap Styles
 Colour-Map Styles
 -----------------
 
-Colour-map Styles are `styles <https://datacube-ows.readthedocs.io/en/latest/cfg_styling.html>`_ where
+:doc:`Colour-map Styles <cfg_styling>` are where
 each pixel is mapped to one particular colour from a fixed pallet
 by applying a logical decision tree to the flag data for that pixel.
 
@@ -118,7 +118,7 @@ Rules
 Each Value Rule must also specify the rule to evaluate when it applies.
 
 For details, refer to the
-`OWS Masking Syntax <https://datacube-ows.readthedocs.io/en/latest/cfg_masks.html>`_.
+:doc:`OWS Masking Syntax <cfg_masks>`.
 
 ------
 Legend
@@ -339,7 +339,7 @@ Aggregator function
 ===================
 
 Alternately, you can define an aggregator function using OWS's
-`function configuration format <https://datacube-ows.readthedocs.io/en/latest/cfg_functions.html>`_.
+:doc:`function configuration format <cfg_functions>`.
 
 The function is passed a multi-date Xarray Dataset and is expected to return a timeless Dataset,
 which can then be rendered using either the single-date value-map, or a separate single-date value-map

docs/cfg_colourramp_styles.rst

@@ -8,7 +8,7 @@ OWS Configuration - Colour-Ramp Styles
 Colour-Ramp Styles
 ------------------
 
-Colour-ramp Styles are `styles <https://datacube-ows.readthedocs.io/en/latest/cfg_styling.html>`_ where
+Colour-ramp Styles are :doc:`styles <cfg_styling>` where
 a single continuous index value is calculated from the raw data for
 each pixel, and that index value is mapped to a graduated colour ramp
 for display.
@@ -19,10 +19,12 @@ Colour-ramp styles support the
 Colour-ramp styles support automatic legend generation. Specialised
 legend configuration is described `below <#legend-configuration>`__.
 
-Note on spelling: I am Australian and spell it "colour".  Most software
-packages use the US spelling "color".  Within the configuration file
-format we use the software conventional spelling, but within the text
-of this documentation, I use the UK/Australian spelling.
+.. note:: On spelling
+
+   I am Australian and spell it "colour". Most software
+   packages use the US spelling "color". Within the configuration file
+   format we use the software conventional spelling, but within the text
+   of this documentation, I use the UK/Australian spelling.
 
 
 ---------------------------
@@ -67,11 +69,11 @@ index_function
 
 The ``index_function`` allows the user to declare a callback function
 to calculate the index value using OWS's
-`function configuration format <https://datacube-ows.readthedocs.io/en/latest/cfg_functions.html>`_.
+:doc:`function configuration format <cfg_functions>`.
 The function is expected to take an xarray Dataset containing all the
 bands in the `needed_bands list <#needed-bands-list>`__ (plus any additional
 arguments handled by the
-`function configuration format <https://datacube-ows.readthedocs.io/en/latest/cfg_functions.html>`_); and returns
+:doc:`function configuration format <cfg_functions>`); and returns
 an xarray Dataset containing the index value.
 
 A `small library <https://datacube-ows.readthedocs.io/en/latest/cfg_functions.html#band-utils-functions>`_
@@ -555,7 +557,7 @@ aggregator_function
 
 The ``aggregator_function`` entry is required for colour ramp style
 multi-date handlers.  It is a function defined using OWS's
-`function configuration format <https://datacube-ows.readthedocs.io/en/latest/cfg_functions.html>`_.
+:doc:`function configuration format <cfg_functions>`.
 
 The first argument passed to the function depends on the value of the ``pass_raw_data``
 element, as described above. The function should return an xarray DataArray with no time

docs/cfg_component_styles.rst

@@ -7,7 +7,7 @@ OWS Configuration - Components
 Component Styles
 ----------------
 
-Component Styles are `styles <https://datacube-ows.readthedocs.io/en/latest/cfg_styling.html>`_ where
+Component Styles are :doc:`styles <cfg_styling>` where
 each component channel of the image (red, green, blue and optionally
 alpha) is calculated independently from the data for that pixel.
 
@@ -228,7 +228,7 @@ Callback Function Components
 +++++++++++++++++++++++++++++
 
 In a callback function component, the user declares a callback function
-using OWS's `function configuration format <https://datacube-ows.readthedocs.io/en/latest/cfg_functions.html>`_.
+using OWS's :doc:`function configuration format <cfg_functions>`.
 
 The function must take an xarray Dataset containing the raw band data
 and return a xarray DataArray containing the channel data.  It is

docs/cfg_functions.rst

@@ -283,6 +283,7 @@ E.g. Using arcsec of the sdev band as a local brightness control for an rgb imag
 The raw red,green,blue bands go to 3000.
 
 ::
+
     "components": {
         "red": {
             "function": "datacube_ows.band_utils.single_band_arcsec",

docs/cfg_global.rst

@@ -7,8 +7,8 @@ OWS Configuration - Global Section
 Global Section
 --------------
 
-The "global" section of the `root configuration object
-<https://datacube-ows.readthedocs.io/en/latest/configuration.html>`_
+The "global" section of the :doc:`root configuration object
+<configuration>`
 contains config entries that apply
 to all services and all layers/coverages.
 
@@ -22,7 +22,7 @@ The following global configuration items are relevant to
 <https://datacube-ows.readthedocs.io/en/latest/configuration.html#metadata-separation-and-internationalisation>`_.
 
 Message File (message_file)
-+++++++++++++++++++++++++++
+---------------------------
 
 The "message_file" entry gives the path to the message file.
 
@@ -38,20 +38,20 @@ Note: the `message_file` configuration entry is not required (except as an inter
 if `translations_directory` is set.  The order of metadata resolution is:
 
 1) If Internationalisation is active via the `translations_directory` config entry, take the
-   value from the *.mo file corresponding to the best available language match for the request
+   value from the \*.mo file corresponding to the best available language match for the request
    headers.
 2) If a translation for the metadata entry is not available, or if internationalisation is not
    active, get the value from the `message_file` if it is configured.
 3) Otherwise, fallback to the value in the main body of the config.
 
 Message Domain (message_domain)
-+++++++++++++++++++++++++++++++
+-------------------------------
 
 The message domain used by internationalisation.  Defaults to "ows_cfg".
 
 
 Translations Directory (translations_directory)
-+++++++++++++++++++++++++++++++++++++++++++++++
+-----------------------------------------------
 
 The path to the directory containing translation subdirectories.  Traditionally known as "locales".
 Defaults to None, meaning no translation support.
@@ -61,7 +61,7 @@ Required for internationalisation.
 
 
 Supported Languages (supported_languages)
-+++++++++++++++++++++++++++++++++++++++++
+-----------------------------------------
 
 A list of supported languages for internationalisation.  Defaults to English only (``['en']``).
 The first language listed is treated as the default language, and it is assumed that all metadata
@@ -264,7 +264,7 @@ logo
 All of the above elements are optional, but at least one must be
 provided if the attribution section exists.
 
-----------------
+
 Attribution Logo
 ----------------
 

docs/cfg_hybrid_styles.rst

@@ -7,16 +7,16 @@ OWS Configuration - Hybrid Styles
 Hybrid Styles
 -------------
 
-Hybrid styles are an experimental type of `style <https://datacube-ows.readthedocs.io/en/latest/cfg_styling.html>`_ that
+Hybrid styles are an experimental type of :doc:`style <cfg_styling>` that
 return a linear combination of a component style and a colour ramp style.
 
 This can allow for a more easily visually interpreted image, but
 there are usually better ways to achieve the same effect on the
 client side.
 
 Hybrid styles support most [*]_ elements supported by either
-`component styles <https://datacube-ows.readthedocs.io/en/latest/cfg_component_styles.html>`_ or
-`colour ramp styles <https://datacube-ows.readthedocs.io/en/latest/cfg_colourramp_styles.html>`_ and
+:doc:`component styles <cfg_component_styles>` or
+:doc:`colour ramp styles <cfg_colourramp_styles>` and
 define two independent styles (one of each type) that
 are then blended according to the required `component_ratio` entry.
 

docs/cfg_layers.rst

@@ -7,8 +7,8 @@ OWS Configuration - Layers
 Layers Section
 ==============
 
-The "layers" section of the `root configuration object
-<https://datacube-ows.readthedocs.io/en/latest/configuration.html>`_
+The "layers" section of the :doc:`root configuration object
+<configuration>`
 contains definitions of the various layers (WMS/WMTS)
 and coverages (WCS) that installation serves.
 
@@ -245,8 +245,8 @@ E.g.
     }
 
 If the
-`manual merge option in the
-image_processing section discussed below<#manual-merge-manual-merge>`_
+:ref:`manual merge option in the
+image_processing section discussed below <manual-merge-manual-merge>`
 is set to ``True``, then overlapping products are layered according to the priority
 order specified in ``product_names``
 
@@ -313,8 +313,8 @@ A date-aware product can be presented as a single-date mosaic layer with no publ
 dimension with the optional `mosaic_date_func` element.
 
 If supplied, the ``mosaic_date_func`` must be a function, declared
-using OWS's `function configuration format
-<https://datacube-ows.readthedocs.io/en/latest/cfg_functions.html>`_.
+using OWS's :doc:`function configuration format
+<cfg_functions>`.
 
 The Mosaic Date Function should take a list of available dates and return a tuple of two datetimes
 to be used in the dataset search operation.
@@ -361,7 +361,7 @@ are mapped to user-accessible dates. The acceptable values are:
 
 * "summary"
   Data has time dimension based on the start date of start datetime of datasets,
-  which are expected to have a `00:00:00.0000+00" time portion.
+  which are expected to have a `00:00:00.0000+00` time portion.
 
   Used for daily, weekly, monthly, quarterly or annual summary data.
 
@@ -417,7 +417,7 @@ Regular Time Axis (time_axis)
 
 The time axis is how OWS publishes the dates for which data is available.  The default
 behaviour (``time_axis`` not specified or ``None``) is to use an irregular time axis, where the available dates
-(as cached in `the OWS range tables <datacube-ows-update <https://datacube-ows.readthedocs.io/en/latest/database.html>`_)
+(as cached in :doc:`the OWS range tables <datacube-ows-update <database>`)
 are listed individually.  These long lists of dates lead to unnecessarily large capabilities documents
 for all supported protocols.
 
@@ -525,8 +525,8 @@ of data urls for authentication (e.g. Microsoft Planetary Computer).  They may a
 to handle various network proxying or data-migration scenarios where the URLs visible to the
 OWS server are different to the URLs at indexing time.
 
-The "patch_url_function" config element is set using OWS's `function configuration format
-<https://datacube-ows.readthedocs.io/en/latest/cfg_functions.html>`_.
+The "patch_url_function" config element is set using OWS's :doc:`function configuration format
+<cfg_functions>`.
 The function is expected to take a string containing an unpatched url and return a
 string containing the patched url.
 
@@ -866,7 +866,7 @@ An additional element, ``describe_cache_maxage`` is also provided,
 which controls the cache control headers for WCS DescribeCoverage requests
 for the coverage/layer.  This element is optional, and defaults
 to the value set in the
-`top-level WCS section<https://datacube-ows.readthedocs.io/en/latest/cfg_wcs.html#describeconverage-default-cache-control-headers-default-desc-cache-maxage>`_
+`top-level WCS section <https://datacube-ows.readthedocs.io/en/latest/cfg_wcs.html#describeconverage-default-cache-control-headers-default-desc-cache-maxage>`_
 
 ++++++++++++
 max_datasets
@@ -933,8 +933,8 @@ use:
     "extent_mask_func": "datacube_ows.ogc_utils.mask_by_val",
 
 If this is not appropriate or possible for your data, you can
-set an alternative function using OWS's `function configuration format
-<https://datacube-ows.readthedocs.io/en/latest/cfg_functions.html>`_.  Some sample functions are included in ``datacube_ows.ogc_utils``.
+set an alternative function using OWS's :doc:`function configuration format
+<cfg_functions>`.  Some sample functions are included in ``datacube_ows.ogc_utils``.
 
 The function is assumed to take two arguments, data (an xarray Dataset) and
 band (a band name).  (Plus any additional arguments you may be passing in
@@ -979,8 +979,8 @@ Fuse Function (fuse_func)
 +++++++++++++++++++++++++
 
 Determines how multiple dataset arrays are compressed into a
-single time array. Specified using OWS's `function configuration
-format <https://datacube-ows.readthedocs.io/en/latest/cfg_functions.html>`_.
+single time array. Specified using OWS's :doc:`function configuration
+format <cfg_functions>`.
 
 The fuse function is passed through to directly to the datacube
 load_data() function - refer to the Open Data Cube documentation
@@ -1241,7 +1241,7 @@ Custom Layer Includes (custom_includes)
 is optional and defaults to an empty dictionary (i.e. no custom data.)
 
 ``custom_includes`` is dictionary mapping keys to functions specified with
-OWS's `function configuration format <https://datacube-ows.readthedocs.io/en/latest/cfg_functions.html>`_.
+OWS's :doc:`function configuration format <cfg_functions>`.
 
 The keys of the "custom_includes" dictionary are the keys that will be included in the
 GetFeatureInfo responses.  They should therefore be keys that are not included by
@@ -1291,11 +1291,11 @@ is optional and defaults to an empty dictionary (i.e. no custom data.)
 Legacy ``include_custom`` entries can be over-ridden by new-style ``custom-includes``.
 
 
------------------------------------
+-------------------------
 Styling Section (styling)
------------------------------------
+-------------------------
 
-The `"styling" section <https://datacube-ows.readthedocs.io/en/latest/cfg_styling.html>`_ describes the WMS and WMTS styles for
+The :doc:`"styling" section <cfg_styling>` describes the WMS and WMTS styles for
 the layer.
 
 

docs/cfg_style_api.rst

@@ -125,7 +125,7 @@ There are two API functions that provide this functionality: ``apply_ows_style``
 
 For more detailed examples,
 refer to the
-`styling how-to guide <https://datacube-ows.readthedocs.io/en/latest/styling_howto.html>`_.
+:doc:`styling how-to guide <styling_howto>`.
 
 Saving or Displaying Images
 ---------------------------