adapting code to match current pygeoapi

Author: ricardogsilva

docs/development.md

@@ -1,40 +1,60 @@
 # Development
 
+## Installation
+
 Install this project with uv
 
 ```shell
 git clone
 uv sync
 ```
 
-Start the prefect server:
 
-```shell
-uv run prefect server start
-```
+## Set-up
 
-Update the prefect config, as directed by the prefect server:
+Prepare a `.env` suitable for development, similar to:
 
-```shell
-uv run prefect config set PREFECT_API_URL=http://127.0.0.1:4200/api
+```dotenv
+# prefect variables
+PREFECT_API_URL=http://127.0.0.1:4200/api
+PREFECT_SERVER_ANALYTICS_ENABLED=false
+DO_NOT_TRACK=1
+
+# pygeoapi variables
+PYGEOAPI_CONFIG=example-config.yml
+PYGEOAPI_OPENAPI=example-openapi.yml
 ```
 
-If you want to deploy a pygeoapi process locally with prefect, then also start a prefect agent:
+!!! WARNING
+
+    We recommend naming the env file `pygeoapi-prefect.env` and sourcing it like this:
+
+    ```shell
+    set -o allexport; source pygeoapi-prefect.env; set +o allexport
+    ```
+
+    All following examples assume the env file has already been sourced.
+
+
+Start the prefect server:
 
 ```shell
-uv run prefect agent start --work-queue pygeoapi
+uv run prefect server start
 ```
 
-Now stand up pygeoapi with the provided config files:
+The prefect UI shall now be available at http://localhost:4200
+
+
+If you want to deploy a pygeoapi process locally with prefect, then also start a prefect agent:
 
 ```shell
-PYGEOAPI_CONFIG=example-config.yml PYGEOAPI_OPENAPI=example-openapi.yml uv run pygeoapi serve
+uv run prefect agent start --type process --pool pygeoapi
 ```
 
-If you need to regenerate the openapi description file, run:
+Now stand up pygeoapi
 
 ```shell
-uv run pygeoapi openapi generate example-config.yml > example-openapi.yml
+uv run pygeoapi serve --starlette
 ```
 
 Deploy the `hi-prefect-world` process:
@@ -50,20 +70,42 @@ uv run prefect deployment run --param
 ```
 
 
-- List processes
+## Operations
+
+
+!!! TIP
+
+    All examples below use:
+
+    - [httpie](https://httpie.io/) as a CLI HTTP client;
+    - [jq](https://jqlang.org/) as a CLI JSON processor;
+
+
+-  List available process ids
+
+    ```shell
+    http localhost:5000/processes | jq '.processes[].id'
+    ```
+
+-  Retrieve details about a process (for example the process with id `hello-world`):
+
+    ```shell
+    http localhost:5000/processes/hello-world | jq '.'
+    ```
 
-  ```shell
-  http -v localhost:5000/processes
-  ```
+-  Execute the pygeoapi `hello-world` process, via prefect. In this example we pass a JSON object
+   with the inputs that the process needs:
 
-- Execute the standard `hello-world` process via prefect:
+    ```shell
+    http localhost:5000/processes/hello-world/execution \
+        inputs:='{"message": "Yo", "name": "planet Earth"}'
+    ```
 
-  ```shell
-  http -v localhost:5000/processes/hello-world/execution inputs:='{"message": "Yo", "name": "planet Earth"}'
-  ```
+    Prefect records flow run executions - you can check them in the Prefect UI, under `runs`
 
-- Execute our `hi-prefect-world` process:
+-  Execute our `hi-prefect-world` process:
 
-  ```shell
-  http -v localhost:5000/processes/hi-prefect-world/execution inputs:='{"message": "Yo", "name": "planet Earth"}'
-  ```
+    ```shell
+    http -v localhost:5000/processes/hi-prefect-world/execution \
+        inputs:='{"message": "Yo", "name": "planet Earth"}'
+    ```