update documentation

README.md

@@ -6,11 +6,24 @@ Elle reprend l'objectif initial de pouvoir vérifier la cohérence entre les don
 
 A ce stade, les principales modifications sont les suivantes:
 
-- Intégration dands un CLI (via le module Click) avec la possibilité également de l'utiliser comme une application dédiée (via le module Python Prompt Toolkit). 
+- Intégration dands un CLI (via le module Click) avec la possibilité également de l'utiliser comme une application dédiée (via le module Python Prompt Toolkit).
-- Ajout de la notion "d'audits" (enregistrement au format JSON de tests préenregistrés).
+- Ajout de la notion "d'audits" : gestion et exécution de tests préenregistrés au format JSON.
 - Séparation des logs (cf. classe libs/logs.py) et des rapports (cf. classe libs/reports.py) afin de pouvoir les enregistrer dans différents formats (JSON, CSV, etc.)
 
-Installation:
+## Concepts
+
+![Concepts](./docs/SDI-CHECKER_concepts.png)
+
+- SERVICE : désigne un service web accessible via un URL (ex. : https://sdi.georchestra.org/geoserver/wfs). Le service doit être indépendant de la solution logicielle utilisée (GeoServer, GeoNetwork ou autre). Il se caractérise principalement par son type : « WMS », « WFS » ou « CSW ». Les services WMS et WFS étant similaires, le cas échéant ils sont regroupés sous la terminologie « WxS ».
+- COLLECTION : sous-ensemble d’éléments (ITEMS) retournés par le service interrogé. Il regroupe un ensemble d’ITEMS. Il peut par exemple s’agir d’un espace de travail (workspace) dans le cas de l’utilisation de GeoServer.
+- ITEM : élément unitaire testé par SDI CHECKER. Dans le cas de flux WMS et WFS on parlera de « LAYER », dans le cas de CSW on parlera de « METADATA » ou « MD »
+- LAYER : ITEM provenant d’une SERVICE/COLLECTION de type WxS
+- MD : ITEM provenant d’une SERVICE/COLLECTION de type CSW
+- AUDIT : correspond à une vérification de conformité sur un SERVICE, une COLLECTION ou un ITEM. Il donne lieu à un REPORT
+- REPORT : rapport issu d’un ensemble de CHECKS appliqué à un SERVICE, une COLLECTION ou un ITEM.
+- CHECK : il s’agit d’une vérification unitaire de cohérence et validité d’une information d’un ITEM. Une vérification porte généralement sur un ensemble de CHECKS appliqué à un ITEM.
+
+## Installation
 
 ```
 $ git clone ...
@@ -21,10 +34,10 @@ $ source ./venv/bin/activate  # linux
 $ pip install -r requirements.txt
 ```
 
-Utilisation:
+## Utilisation
 
 ```
-# Créer un premier audit 
+# Créer un premier audit
 $ python .\sdi-checker.py audits add --url https://www.datagrandest.fr/geoserver/araa/ows --name 'WMS de l'ARAA' --type WMS
 
 Liste des audits
@@ -35,7 +48,7 @@ Nb. audits: 3/3
 | 0  | WMS de l'ARAA | WMS  | https://www.datagrandest.fr/geoserver/araa/ows |
 +----+---------------+------+------------------------------------------------+
 
-# Créer un second audit 
+# Créer un second audit
 $ python .\sdi-checker.py audits add --url https://www.datagrandest.fr/geoserver/araa/ows --name 'WFS de l'ARAA' --type WFS
 
 Liste des audits
@@ -47,7 +60,7 @@ Nb. audits: 3/3
 | 1  | WMS de l'ARAA | WFS  | https://www.datagrandest.fr/geoserver/araa/ows |
 +----+---------------+------+------------------------------------------------+
 
-# Créer un troisième audit 
+# Créer un troisième audit
 $ python .\sdi-checker.py audits add --url https://www.datagrandest.fr/geoserver/wfs --name 'Audit de test' --type WFS
 
 Liste des audits
@@ -112,11 +125,33 @@ $ python .\sdi-checker.py check wfs https://www.datagrandest.fr/geoserver/araa/o
 
 ## Organisation des fichiers
 
-- 1 fichier JSON avec la liste des audits et leurs paramètres
+### Organisation du code
+
+Un point d'entrée unique dans l'application : 
+
+```
+$ python ./sdi-checker.py [MODE]
+```
+
+Une classe centrale permet de gérer l'application : `./sdi_checker/app/application.py`.
+
+Plusieurs mode d'exécution:
+- 'cli' (par défaut) : `./sdi_checker/app_cli/application.py`
+- 'web' (serveur bottle) : `./sdi_checker/app_web/application.py`
+
+Possibilité ainsi d'étendre avec une version desktop au besoin ('gui'), etc.
+
+Les librairies utilisées sont organisés sous forme de classes dans `./sdi_checker/libs`.
+
+Pour l'application CLI les commandes et sous-commandes sont définies dans `./sdi_checker/app_cli/commands` : un fichier par commande et un répertoire correspodnant pour les sous-commandes (cf. section 'Liste des commandes' ci-dessous).
+
+### Gestion de la liste des audits
+
+Un fichier JSON avec la liste des audits et leurs paramètres
 
 Fichier "audits.json"
 
-``` json
+```json
 [{
     "id": "md5"
     "name": "wms_araa"
@@ -132,11 +167,11 @@ Fichier "audits.json"
 
 ### audits
 
-#### list/ls                   = liste les audits déjà renseignés
+#### list/ls = liste les audits déjà renseignés
 
 Paramètres:
 
-- SEARCH                = filtrer la liste des audits contenant le terme "SEARCH"
+- SEARCH = filtrer la liste des audits contenant le terme "SEARCH"
 
 #### add
 
@@ -154,11 +189,10 @@ Paramètres:
 - disable-ssl-verification
 - only-err
 - xunit
-- xunit-output XUNIT_OUTPUT 
+- xunit-output XUNIT_OUTPUT
 - log-to-file LOG_TO_FILE
 - timeout TIMEOUT
 
-
 #### delete/remove/del/rm
 
 Objectif : supprimer un audit
@@ -250,7 +284,7 @@ Paramètres:
 Cette API a vocation a pemrttre de générer et consulter des rapports pour une réutilisation dans d'autres applications.
 Les bases du ode se situent dans `sdi-checker/app_web`.
 
-**!! Les fonctionnalités de consultation des rapports et erreurs (ex.: http://127.0.0.1:8001/reports) ne sont actuellement plus fonctionnels suite à une modification profonde du fonctionnement de l'application SDI Checker.**
+**!! Les fonctionnalités de consultation des rapports et erreurs (ex.: http://127.0.0.1:8001/reports) ne sont actuellement plus fonctionnelles suite à une modification importante du code de l'application SDI Checker.**
 
 Utilisation:
 
@@ -260,6 +294,7 @@ $ python .\sdi-checker.py web [MODE]
 ```
 
 Les modes possibles sont:
+
 - 'prod' (défaut) : ouvre Webview
 - 'dev' : ouvre Webview en mode développement
 - 'browser' : ouvre l'application dans le navigateur