diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1d2c94f..4ed3ec1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,8 +12,10 @@ - [Vérifier si une instance existante serait réutilisable](#vérifier-si-une-instance-existante-serait-réutilisable) - [Si aucune instance n'est réutilisable](#si-aucune-instance-nest-réutilisable) - [swagger.json de base](#swaggerjson-de-base) - - [Dans tous les cas](#dans-tous-les-cas) - - [Création du `.ini`: `v1/service.ini`](#création-du-ini-v1serviceini) + - [Création du .ini: v1/service.ini](#création-du-ini-v1serviceini) + - [Métadonnées de base](#métadonnées-de-base) + - [mimeType = application/json](#mimetype--applicationjson) + - [post.operationId](#postoperationid) - [Python](#python) - [version de python](#version-de-python) - [Utiliser un environnement virtuel](#utiliser-un-environnement-virtuel) @@ -40,6 +42,8 @@ - [Vérifier que le swagger fonctionne](#vérifier-que-le-swagger-fonctionne) - [catalogues LODEX](#catalogues-lodex) - [Objectif TDM](#objectif-tdm) + - [Fiche du service](#fiche-du-service) + - [Article d'annonce](#article-dannonce) ## Développement @@ -220,17 +224,64 @@ > ![tags de l'OpenAPI](images/openapi-tags.png) -#### Dans tous les cas +#### Création du .ini: v1/service.ini -##### Création du .ini: v1/service.ini +Le chemin du `.ini` détermine la route du service. -Chemin du .ini détermine la route du service. -Avec les métadonnées de base: description, summary, tags... -Modèle de base en ezs pur / avec python. -À COMPLÉTER +Par exemple, le fichier `terms-extraction/v1/teeft/en.ini` donnera l'URL +`https://terms-extraction.services.inist.fr/v1/teeft/en`, dont la route est +`v1/teeft/en`. + +Il faut donc bien réfléchir au chemin du fichier. + +De même, le mieux est d'avoir une route courte, plus facile à retenir, à taper +sans faute de frappe, ... + +Il est donc inutile de créer le `.ini` dans un chemin dont une partie n'aurait +pas de signification (par exemple: `terms-extraction/v1/teeft/en/expand.ini`, +ici la partie `/expand` n'a aucune utilité). +On n'a besoin de répertoire que quand il faut y placer au moins deux services +(deux `.ini`) différents. + +#### Métadonnées de base + +Les métadonnées du service sont écrites dans le fichier `.ini`. +C'est le serveur `ezs` qui les interprète et les utilise pour la route du +service, ou pour les intégrer dans le swagger qui sera utilisé sur +`openapi.services.inist.fr`. + +N'hésitez pas à ajouter des commentaires dans le fichier. +Il suffit de commencer une ligne par `#` ou par `;`. + +##### mimeType = application/json + +La première ligne à ajouter est: + +```ini +mimeType = application/json +``` + +##### post.operationId + +Chaque service doit avoir un identifiant unique (ça permet d'avoir des liens +uniques dans OpenAPI, et de nommer les requêtes dans `examples.http`). + +La convention pour construire cet identifiant est de partir du chemin du fichier +`.ini`, de supprimer le `.ini`, et de remplacer chaque `/` par un `-`; il faut +aussi le commencer par la méthode HTTP utilisée (pour les services web, c'est +`post` sauf exception). + +Ainsi, `terms-extraction/v1/teeft/en.ini` se traduit en `post-v1-teeft-en`. + +À CONTINUER... +Avec les métadonnées de base: description, summary, tags... +Modèle de base en ezs pur / avec python. À COMPLÉTER ### Python +Relation `.ini` . `.py` +Exemple de `.ini` et structure de base du `.py`. + #### version de python #### Utiliser un environnement virtuel @@ -295,6 +346,7 @@ 1. ajouter l'instance dans `internal-proxy` À COMPLÉTER 2. ajouter l'instance dans `internal-monitoring` À COMPLÉTER +3. changer le `title` dans la configuration À COMPLÉTER ## Après le déploiement @@ -326,6 +378,8 @@ ### Objectif TDM + + #### Fiche du service La fiche d'un service web doit avoir (le titre d'une section sera en style @@ -337,7 +391,7 @@ donc aller droit au but, pas besoin de construire une phrase. Si la phrase est trop longue, il est possible qu'on n'en voie que le début - **description**: plus longue et détaillée que le sous-titre, décrit ce que - fait le service web. + fait le service web. Y compris les paramètres éventuels (`indent` ou autre). - **image**: idéalement, un usage de l'enrichissement dans LODEX - **algorithme**: une section consacrée à la manière dont fonctionne le service (est-ce un apprentissage, une heuristique, ...) @@ -348,7 +402,8 @@ aussi (procédure à déterminer pour pouvoir comparer les services entre eux) - **corpus d'apprentissaga / test**: sur quelles données s'appuient les tests et/ou l'apprentissage -- **références**: bibliographie + code source (liens) +- **références**: bibliographie + code source (liens) + éventuel URL variante + (anglais/français par exemple) Exemple de sous-titre trop long: @@ -387,5 +442,41 @@ > ![recherche de services web](images/objectif-tdm-recherche.png) +> **Note**: c'est toujours mieux de faire relire avant de publier, mettez vos +> collègues à contribution ;) + #### Article d'annonce +Une fois que la fiche est publiée, on peut écrire l'article d'annonce de la +nouveauté (que ce soit une correction, un nouveau service web, ...). + +Catégories à cocher: `Blog` *et* `Blog/Webservices`. + +> ![catégories blog/Webservices](images/objectif-tdm-categories-blog.png) + +Ajouter aussi l'image mise en avant. + +> ![lien de choix de l'image](images/objectif-tdm-choix-image.png) + +Pour une annonce de service web, utilisez l'image `Webservices`: + +> ![l'image Webservices](images/objectif-tdm-image-webservices.png) + +C'est elle qui d'un coup d'œil permet de savoir de quoi parle un article du +blog, dans la liste anté-chronologique. + +Trouvez un titre pas trop long, et soyez conscient que le premier paragraphe de +l'article sera aussi présent dans la fameuse [liste des +articles](https://objectif-tdm.inist.fr/category/actualites/). + +> ![liste des articles](images/objecti-tdm-liste-articles.png) + +L'article doit expliquer la raison de la modification annoncée (si c'est un +nouveau service, ce qu'il est censé faire, si c'est une amélioration, ce qui +n'allait pas et comment ça a été résolu). + +Il ne faut pas oublier de faire référence à la fiche du service (et de mettre un +lien). + +D'ailleurs, une fois que cet article est publié, il faut l'ajouter aux +références de la fiche. diff --git a/images/objecti-tdm-liste-articles.png b/images/objecti-tdm-liste-articles.png new file mode 100644 index 0000000..6b7775c --- /dev/null +++ b/images/objecti-tdm-liste-articles.png Binary files differ diff --git a/images/objectif-tdm-categories-blog.png b/images/objectif-tdm-categories-blog.png new file mode 100644 index 0000000..effb066 --- /dev/null +++ b/images/objectif-tdm-categories-blog.png Binary files differ diff --git a/images/objectif-tdm-choix-image.png b/images/objectif-tdm-choix-image.png new file mode 100644 index 0000000..12a5355 --- /dev/null +++ b/images/objectif-tdm-choix-image.png Binary files differ diff --git a/images/objectif-tdm-image-webservices.png b/images/objectif-tdm-image-webservices.png new file mode 100644 index 0000000..8a5a26a --- /dev/null +++ b/images/objectif-tdm-image-webservices.png Binary files differ