Re-add $

pblottiere · Nov 20, 2024 · 56b558a · 56b558a
1 parent c357102
commit 56b558a
Show file tree

Hide file tree

Showing 16 changed files with 106 additions and 164 deletions.
diff --git a/docs/src/DEVELOPERS.md b/docs/src/DEVELOPERS.md
@@ -3,12 +3,12 @@
 ## Documentation
 
 ```` console
-mdbook build docs
+$ mdbook build docs
 ````
 
 ## Unit tests
 
-ensure you have a valid `~/.pg_service.conf`
+Ensure you have a valid `qsa_test` section in `~/.pg_service.conf`:
 
 ```` conf
 [qsa_test]
@@ -19,26 +19,28 @@ user=myusername
 password=
 ````
 
-run the tests with:
+Run the tests with:
 
 ```` console
-createdb qsa_test
-cd qsa-api
-pytest -sv tests
+$ createdb qsa_test
+$ cd qsa-api
+$ pytest -sv tests
 ````
 
 ## Integration tests
 
 ```` console
-cd sandbox
-docker-compose up -d
-cd ../qsa-api
-QSA_GEOTIFF="/landsat_4326.tif" QSA_GPKG="/data.gpkg" QSA_HOST=127.0.01 QSA_PORT=5000 pytest -sv tests
+$ cd sandbox
+$ docker-compose up -d
+$ cd ../qsa-api
+$ QSA_GEOTIFF="/landsat_4326.tif" QSA_GPKG="/data.gpkg" QSA_HOST=127.0.01 QSA_PORT=5000 pytest -sv tests
 ````
 
-Ensure your changes are correctly formatted with `pre-commit` (see [installation](https://pre-commit.com/#installation))
+## Quality tests
+
+Ensure your changes are correctly formatted with `pre-commit` (see [installation](https://pre-commit.com/#installation)):
 
 ```` console
 # activate in repository
-pre-commit install
+$ pre-commit install
 ````
diff --git a/docs/src/qsa-api/configuration.md b/docs/src/qsa-api/configuration.md
@@ -28,9 +28,9 @@ well as QGIS QML styles.
 
 The PostgreSQL support relies on a `service` defined in a [PostgreSQL connection
 service file](https://www.postgresql.org/docs/current/libpq-pgservice.html).
-For example with `QSA_QGISSERVER_PROJECTS_PSQL_SERVICE=qsa_projects`:
 
-Ensure you have a valid `~/.pg_service.conf`
+For example with `QSA_QGISSERVER_PROJECTS_PSQL_SERVICE=qsa_projects`, a proper
+`qsa_projects` section is needed in `~/.pg_service.conf`:
 
 ```` conf
 [qsa_projects]

diff --git a/docs/src/qsa-api/endpoints/README.md b/docs/src/qsa-api/endpoints/README.md
@@ -13,7 +13,7 @@ When PostgreSQL support is enabled, a query string parameter `schema` may be
 used to specify the schema in which the QGIS project is stored in the database
 (`public` is used by default).
 
-```` shell
+```` console
 # call a specific endpoint using projects stored in PostgreSQL schema named `myschema`
-curl "http://localhost/api/xxx/yyy?schema=myschema"
+$ curl "http://localhost/api/xxx/yyy?schema=myschema"
 ````
diff --git a/docs/src/qsa-api/endpoints/processing.md b/docs/src/qsa-api/endpoints/processing.md
@@ -10,7 +10,7 @@ rasters or get histogram for raster layers.
 
 Examples:
 
-``` shell
+``` console
 # create a new layer based on a QGIS expression
 $ curl "http://localhost/api/projects/" \
      -X POST \

diff --git a/docs/src/qsa-api/endpoints/projects.md b/docs/src/qsa-api/endpoints/projects.md
@@ -18,9 +18,9 @@ A QSA project is defined by:
 
 Examples:
 
-``` shell
+``` console
 # create a project and store the QGIS project in PostgreSQL within `my_schema`
-curl "http://localhost/api/projects/" \
+$ curl "http://localhost/api/projects/" \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{
@@ -30,7 +30,7 @@ curl "http://localhost/api/projects/" \
      }'
 
 # get metadata about the project stored in PostgreSQL
-curl "http://localhost/api/projects/my_project?schema=my_schema"
+$ curl "http://localhost/api/projects/my_project?schema=my_schema"
 ```
 
 ## Layer
@@ -69,9 +69,9 @@ A layer can be added to a project thanks to the next parameters:
 
 Example:
 
-```` shell
+```` console
 # Add a FlatGeobuf vector layer stored on S3 bucket in project `my_project`
-curl "http://localhost/api/projects/my_project/layers" \
+$ curl "http://localhost/api/projects/my_project/layers" \
   -X POST \
   -H 'Content-Type: application/json' \
   -d '{
@@ -108,9 +108,9 @@ For vector layers, a style can be defined with the parameters listed below:
 
 Example:
 
-```` shell
+```` console
 # Add a style for point geometry vector layers
-curl "http://localhost:5000/api/projects/my_project/styles" \
+$ curl "http://localhost:5000/api/projects/my_project/styles" \
   -X POST \
   -H 'Content-Type: application/json' \
   -d '{
@@ -146,9 +146,9 @@ For raster layers, a style can be defined with the parameters listed below:
 
 Example:
 
-```` shell
+```` console
 # Add a style for multiband raster
-curl "http://localhost:5000/api/projects/my_project/styles" \
+$ curl "http://localhost:5000/api/projects/my_project/styles" \
   -X POST \
   -H 'Content-Type: application/json' \
   -d '{
@@ -186,7 +186,7 @@ curl "http://localhost:5000/api/projects/my_project/styles" \
 
 Example:
 
-```` shell
+```` console
 $ curl "http://localhost:5000/api/projects/my_project/cache"
 {
   "valid":true,

diff --git a/docs/src/qsa-api/endpoints/symbology.md b/docs/src/qsa-api/endpoints/symbology.md
@@ -23,14 +23,9 @@ version.
 
 Examples:
 
-```` shell
+```` console
 # Return single symbol properties for polygon layers
-curl "http://localhost:5000/api/symbology/vector/polygon/single_symbol/fill/properties" | jq
-````
-
-returns
-
-```` json
+$ curl "http://localhost:5000/api/symbology/vector/polygon/single_symbol/fill/properties" | jq
 {
   "border_width_map_unit_scale": "3x:0,0,0,0,0,0",
   "color": "0,0,255,255",
@@ -48,12 +43,7 @@ returns
 
 ```` console
 # Return multi band gray properties for raster layers
-curl "http://localhost:5000/api/symbology/raster/multibandcolor/properties" | jq
-````
-
-returns
-
-```` json
+$ curl "http://localhost:5000/api/symbology/raster/multibandcolor/properties" | jq
 {
   "blue": {
     "band": 3,

diff --git a/docs/src/qsa-api/installation.md b/docs/src/qsa-api/installation.md
@@ -2,21 +2,20 @@
 
 ## From sources
 
-```` shell
-cd qsa-api
-virtualenv --system-site-packages venv  # system aware for pyqgis
-. venv/bin/activate
-# now in (venv)
-pip install poetry
-poetry install
+```` console
+$ cd qsa-api
+$ virtualenv --system-site-packages venv  # system aware for pyqgis
+$ . venv/bin/activate
+(venv)$ pip install poetry
+(venv)$ poetry install
 ````
 
 ## Docker image
 
 A prebuilt image can be found on `ghcr.io/pblottiere/qsa`:
 
-```` shell
-docker pull ghcr.io/pblottiere/qsa:1.1.0
+```` console
+$ docker pull ghcr.io/pblottiere/qsa:1.1.0
 ````
 
 Otherwise the image can manually be built using:

diff --git a/docs/src/qsa-cli/installation.md b/docs/src/qsa-cli/installation.md
@@ -3,12 +3,11 @@
 From sources:
 
 ```` console
-cd qsa-cli
-virtualenv venv
-. venv/bin/activate
-# now in (venv)
-pip install poetry
-poetry install
+$ cd qsa-cli
+$ virtualenv venv
+$ . venv/bin/activate
+(venv)$ pip install poetry
+(venv)$ poetry install
 ````
 
 Binary distributions:

diff --git a/docs/src/sandbox/README.md b/docs/src/sandbox/README.md
@@ -5,9 +5,9 @@ QSA tools with PostgreSQL support enabled.
 
 First, a QSA REST API server is set up with 4 QGIS Server instances:
 
-```` shell
-cd sandbox
-docker-compose up --scale qgisserver=4 -d
+```` console
+$ cd sandbox
+$ docker-compose up --scale qgisserver=4 -d
 $ docker ps
 CONTAINER ID   IMAGE                              COMMAND                  CREATED       STATUS         PORTS                                       NAMES
 d2eaf6bdfae4   pblottiere/qsa          "gunicorn -b 0.0.0.0…"   2 hours ago   Up 10 seconds  0.0.0.0:5000->5000/tcp, :::5000->5000/tcp   sandbox-qsa-1

diff --git a/docs/src/sandbox/inspect.md b/docs/src/sandbox/inspect.md
@@ -7,7 +7,7 @@
 
 To list these instances with `qsa-cli`:
 
-```` shell
+```` console
 $ QSA_SERVER_URL=http://localhost:5000 qsa ps
 INSTANCE ID    IP          STATUS
 -------------  ----------  -----------------------
@@ -19,13 +19,8 @@ c0047e66       172.20.0.6  Binded 1096 seconds ago
 
 Or with the API:
 
-```` shell
-curl http://localhost:5000/api/instances/ | jq
-````
-
-returns
-
-```` json
+```` console
+$ curl http://localhost:5000/api/instances/ | jq
 {
   "servers": [
     {
@@ -56,13 +51,8 @@ returns
 
 To get some metadata about a specific QGIS Server instance with `qsa-cli`:
 
-```` shell
-qsa inspect 4464d3c5
-````
-
-returns
-
-```` json
+```` console
+$ qsa inspect 4464d3c5
 {
   "cache": {
     "projects": []
@@ -112,26 +102,16 @@ Or with the API `curl http://localhost:5000/api/instances/4464d3c5`.
 
 A bad request to QGIS Server to have something in the log:
 
-```` shell
-curl http://172.20.0.4/ogc/
-````
-
-returns
-
-````xml
+```` console
+$ curl http://172.20.0.4/ogc/
 <?xml version="1.0" encoding="UTF-8"?>
 <ServerException>Project file error. For OWS services: please provide a SERVICE and a MAP parameter pointing to a valid QGIS project file</ServerException>
 ````
 
 Then to fetch the log of the corresponding QGIS Server instance with `qsa-cli`:
 
-```` shell
-qsa logs 4464d3c5
-````
-
-returns
-
-```` text
+```` console
+$ qsa logs 4464d3c5
 Server plugin qsa loaded!
 Server python plugins loaded
 ******************** New request ***************
@@ -163,13 +143,8 @@ Request finished in 3 ms
 
 To display stats for all QGIS Server online instances:
 
-```` shell
-qsa stats
-````
-
-returns
-
-````text
+```` console
+$ qsa stats
 INSTANCE ID      COUNT  TIME        SERVICE    REQUEST    PROJECT
 -------------  -------  ----------  ---------  ---------  ---------
 4464d3c5             1