Documentation (plus a shot at a simpler Dockerfile)

[omad]

Sorry for the combination of changes in this PR, it's my last day at GA and I'm running out of time...

Docs

The main change here is an attempt to make the Configuration and Usage portions of the docs more visible, since for the longest time I didn't even know they existed. (Tragedy face, since they're brilliant).

In the process, I also fixed almost all the errors and warnings in the docs, some of which were causing breakage and missing elements like the CLI docs.

Dockerfile

I was also experimenting with using the micromamba docker image to build a docker image for OWS. This uses a conda environment specification, pulls packages from conda-forge, and installs datacube-ows. It also tries to minimise the size of the built image.

The image at the moment expects the OWS version to be passed as an argument, since git isn't installed in the image. Instead it's using a pass version by environment variable feature available from setuptools_scm. I've used it like:

docker build --progress plain -t opendatacube/ows:damien-micromamba --file Dockerfile.micromamba --build-arg PSEUDO_VERSION=(git describe --tags --always --dirty | sed -r 's/-([0-9]+)/.dev\1/' | sed 's/-/+/') .

For now, the resultant image is about the same size as before, but IMO is simpler and more maintainable.

What I'm excited about that's coming soon, is to make it a much smaller image. Lots of the size is made up by a monolithic GDAL build pulling in lots of extra transitive libraries, (eg, for PDF support libpoppler -> libcairo -> X11 libs. + NetCDF/HDF + an entire Postgres installation for PGRaster support). GDAL in 3.9.1 added support for dynamically loading libraries, and this lead to a restructure and splitting of the conda-forge libraries. We can't quite make use of it until conda-forge/rasterio-feedstock#303 is merged into the rasterio conda-forge package.

[SpacemanPaul]

Some great stuff in here, but appears to be breaking the build of our test image somehow.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 93.64%. Comparing base (aa67e0b) to head (9338e8f).
Report is 21 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1064   +/-   ##
=======================================
  Coverage   93.64%   93.64%           
=======================================
  Files          43       43           
  Lines        6510     6510           
=======================================
  Hits         6096     6096           
  Misses        414      414           

[SpacemanPaul]

Why are we dropping setuptools_scm as a dependency? You still have it in Dockerfile.micromamba?

[SpacemanPaul]

I'm going to try restoring it and see if that fixes the docker build (as it's the only change here that looks like it may potentially affect it).

[SpacemanPaul]

The invalid 1.8.0-rc1.0 version string is the fallback defined in pyproject.toml but I've no idea what's changed to suddenly make it an issue.

[SpacemanPaul]

Thanks again for squeezing this in @omad

And now for something completely different....