Update sphinx based docs

refs: #117 EOEPCA/roadmap#264

README.md

@@ -67,9 +67,10 @@ The [docker](docker) folder has a `Dockerfile` to build a Docker image, e.g.:
 
     docker build -t openeo-aggregator -f docker/Dockerfile .
 
-This image is built and hosted by VITO at `vito-docker.artifactory.vgt.vito.be/openeo-aggregator`
+This image is built automatically and hosted by VITO at `vito-docker.artifactory.vgt.vito.be/openeo-aggregator`
 
 The image runs the app in gunicorn by default (serving on `127.0.0.1:8000`).
+
 Example usage, with some extra gunicorn settings and the built-in dummy config:
 
     docker run \
@@ -79,7 +80,7 @@ Example usage, with some extra gunicorn settings and the built-in dummy config:
       -e OPENEO_BACKEND_CONFIG=/home/openeo/venv/lib/python3.11/site-packages/openeo_aggregator/config/examples/aggregator.dummy.py \
       vito-docker.artifactory.vgt.vito.be/openeo-aggregator:latest
 
-The webapp should be available at http://localhost:8080/openeo/1.2
+This webapp should be available at http://localhost:8080/openeo/1.2
 
 
 ## Further configuration

docs/pages/configuration.md

@@ -1,15 +1,52 @@
+# Configuration
 
+## Essential configuration
 
-# Configuration
+The openEO-Aggregator specific configuration,
+is grouped by an `AggregatorBackendConfig` container object
+(subclass of `OpenEoBackendConfig` as defined in the `openeo-python-driver` framework project).
+
+The most important config value is `aggregator_backends`, which
+defines the backends to "aggregate".
+See [`src/openeo_aggregator/config/config.py`](https://github.com/Open-EO/openeo-aggregator/blob/master/src/openeo_aggregator/config/config.py)
+for more details and other available configuration options.
+
+Use the env var `OPENEO_BACKEND_CONFIG` to point to the desired config path.
+For example, using the example [dummy config](https://github.com/Open-EO/openeo-aggregator/blob/master/src/openeo_aggregator/config/examples/aggregator.dummy.py)
+from the repo:
+
+```shell
+export OPENEO_BACKEND_CONFIG=src/openeo_aggregator/config/examples/aggregator.dummy.py
+```
+
+
+When no valid openEO-Aggregator is set that way, you typically get this error:
+
+```text
+ConfigException: Expected AggregatorBackendConfig but got OpenEoBackendConfig
+```
+
+
+## Further configuration
+
+The flask/gunicorn related configuration can be set through
+standard flask/gunicorn configuration means
+like command line options or env variables, as shown above.
 
-:::{Attention}
-This documentation page is work in progress... 👷
-:::
+### Gunicorn config
 
+For running with gunicorn, there is an example config at `src/openeo_aggregator/config/examples/gunicorn-config.py`,
+for example to be used like this:
 
-The openEO Aggregator can be configured through a `AggregatorBackendConfig` class
+```shell
+gunicorn --config=src/openeo_aggregator/config/examples/gunicorn-config.py 'openeo_aggregator.app:create_app()'
+```
 
+### Logging
 
-## Gunicorn configuration
+By default, logging is done in JSON format.
+You can switch to a simple text-based logging with this env var:
 
-TODO
+```shell
+OPENEO_AGGREGATOR_SIMPLE_LOGGING=1
+```

docs/pages/installation.md

@@ -1,17 +1,16 @@
-
 # Installation
 
-:::{Attention}
-This documentation page is work in progress... 👷
-:::
-
-
-The openEO Aggregator can be installed via pip:
+The openEO Aggregator is a Python package and can be installed via standard tooling like `pip`.
+While it's possible to install it with a naive `pip install openeo-aggregator`,
+the current build workflows push the related packages to a dedicated repository (instead of PyPI),
+so to install a recent version it is generally recommended to install with
 
 ```shell
-python -m pip install openeo-aggregator
+python -m pip install openeo-aggregator --extra-index-url https://artifactory.vgt.vito.be/api/pypi/python-openeo/simple
 ```
 
+At the time of this writing it is recommended to work with Python 3.11.
+
 
 ## Requirements
 

docs/pages/usage.md

@@ -1,21 +1,55 @@
+# Running the aggregator
 
-# Usage
 
-:::{Attention}
-This documentation page is work in progress... 👷
-:::
+Note: make sure you [point to a valid configuration file](configuration.md)
+before trying to run the web app.
 
 
-## Run with Flask in development mode
+### Flask dev mode
+
+To run locally in development mode, with standard Flask workflow,
+for example (also see `./scripts/run-flask-dev.sh`):
 
 ```shell
-export FLASK_APP='openeo_aggregator.app:create_app()'
+export FLASK_APP=openeo_aggregator.app
 export FLASK_ENV=development
 flask run
 ```
 
-## Run with Gunicorn
+The webapp should be available at http://localhost:5000/openeo/1.2
+
+
+### With gunicorn
+
+To run the app as gunicorn application, with desired options,
+for example (also see `./scripts/run-gunicorn.sh`):
+
+```shell
+gunicorn --workers=4 --bind 0.0.0.0:8080 'openeo_aggregator.app:create_app()'
+```
+
+The webapp should be available at http://localhost:8080/openeo/1.2
+
+
+## Docker image
+
+The [docker](docker) folder has a `Dockerfile` to build a Docker image, e.g.:
 
 ```shell
-gunicorn 'openeo_aggregator.app:create_app()'
+docker build -t openeo-aggregator -f docker/Dockerfile .
 ```
+
+This image is built automatically and hosted by VITO at `vito-docker.artifactory.vgt.vito.be/openeo-aggregator`
+
+The image runs the app in gunicorn by default (serving on `127.0.0.1:8000`).
+
+Example usage, with some extra gunicorn settings and the built-in dummy config:
+
+    docker run \
+      --rm \
+      -p 8080:8080 \
+      -e GUNICORN_CMD_ARGS='--bind=0.0.0.0:8080 --workers=2' \
+      -e OPENEO_BACKEND_CONFIG=/home/openeo/venv/lib/python3.11/site-packages/openeo_aggregator/config/examples/aggregator.dummy.py \
+      vito-docker.artifactory.vgt.vito.be/openeo-aggregator:latest
+
+This webapp should be available at http://localhost:8080/openeo/1.2