Merge pull request #43 from Inist-CNRS/chore/scripts/add-insert-descr…

…iption

Add script to insert description into .ini metadata

.vscode/settings.json

@@ -2,6 +2,7 @@
     "markdownlint.config": {
         "MD024": false, // MD024: Duplicate headings
         "MD028": false, // MD028: Blank line inside blockquote
+        "MD041": false, // MD041: First line in file should be a top level header
         "MD051": false  // MD051: Broken link fragment (ex: #v1/teeft instead of #v1teeft)
     }
-}
+}

CONTRIBUTING.md

@@ -260,6 +260,42 @@ dépôt, et dans la liste des services à la fin du [README](./README#services).
 > ⚠ Ne pas mettre de caractère `&` dans les réponses, ça provoque un
 > remplacement bizarre.
 
+### OpenAPI: ajout d'une description multilignes dans les métadonnées du .ini
+
+Pour avoir une documentation OpenAPI complète, on peut écrire la description
+d'un service en Markdown.  
+On peut se contenter d'écrire cette description dans la métadonnée
+`post.description` directement, en mettant les lignes bout-à-bout, séparées par
+`^M`.  
+Mais il est plus simple d'utiliser le script `./bin/insert-description.sh`, qui
+prend en paramètres un ou plusieurs chemins de fichiers Markdown (`.md`).  
+Pour chaque fichier `.md`, il insère le contenu dans le fichier dont le chemin
+correspond au nom du `.md` (en remplaçant les `_` par des `/`).  
+
+Exemples:
+
+```bash
+./bin/insert-description.sh services/terms-extraction/v1*.md
+./bin/insert-description.sh services/terms-extraction/v1_teeft_fr.md
+```
+
+Alternative: utiliser le script npm `insert:description`:
+
+```bash
+$ npm run insert:description services/terms-extraction/v*.md
+
+> [email protected] insert:description
+> ./bin/insert-description.sh services/terms-extraction/v1_teeft_en.md services/terms-extraction/v1_teeft_fr.md services/terms-extraction/v1_teeft_with-numbers_en.md services/terms-extraction/v1_teeft_with-numbers_fr.md
+
+ - services/terms-extraction/v1/teeft/en.ini ✓
+ - services/terms-extraction/v1/teeft/fr.ini ✓
+ - services/terms-extraction/v1/teeft/with-numbers/en.ini ✓
+ - services/terms-extraction/v1/teeft/with-numbers/fr.ini ✓
+```
+
+> **Note**: si vous voulez bénéficier de l'auto-complétion des chemins de
+> fichiers, utilisez plutôt `./bin/insert-description.sh`.
+
 ## Développement
 
 ### Sans docker

SCRIPTS.md

@@ -6,6 +6,7 @@ Available scripts:
 - generate:example-tests
 - generate:service
 - help
+- insert:description
 - publish
 - update:images
 - test:local
@@ -59,6 +60,29 @@ Help is colorized if you have `bat` installed.
 
 See <https://github.com/sharkdp/bat>.
 
+## insert:description
+
+Usage: `npm run insert:description services/service-name/v1_path.md`
+
+Insert the Markdown description of a route into the matching `.ini` metadata
+(`post.description`).  
+Convert multiline markdown into one-line metadata (using `^M` character).
+Replace the `_` character in the markdown files names with `/`, to match the path of the `.ini`s to be modified.
+
+Example:
+
+```bash
+$ npm run insert:description services/terms-extraction/v*.md
+
+> [email protected] insert:description
+> ./bin/insert-description.sh services/terms-extraction/v1_teeft_en.md services/terms-extraction/v1_teeft_fr.md services/terms-extraction/v1_teeft_with-numbers_en.md services/terms-extraction/v1_teeft_with-numbers_fr.md
+
+ - services/terms-extraction/v1/teeft/en.ini ✓
+ - services/terms-extraction/v1/teeft/fr.ini ✓
+ - services/terms-extraction/v1/teeft/with-numbers/en.ini ✓
+ - services/terms-extraction/v1/teeft/with-numbers/fr.ini ✓
+```
+
 ## publish
 
 Usage: `npm run publish`

bin/insert-description.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+
+
+# Return the content of the file which path is given, replacing line return with
+# "^M".
+# @param {string} path of the file to convert
+# @return {string}
+function markdown2line() {
+    local input_string
+    input_string=$(cat "$1")
+    echo "${input_string//$'\n'/^M}"
+}
+
+# Insert the description in the .ini file
+# @param {string} path of the .md file to convert
+function insert_description() {
+    local DESCRIPTION
+    local CONTAINS_DESCRIPTION
+    local MARKDOWN_PATH
+    local SLASH_PATH
+    local INI_PATH
+    MARKDOWN_PATH=$1
+    SLASH_PATH=${MARKDOWN_PATH//_//}
+    INI_PATH=${SLASH_PATH/%.md/.ini}
+    printf " - %s" "$INI_PATH"
+
+    if [ ! -f "$INI_PATH" ]; then
+        printf " X\n"
+        return
+    fi
+
+    DESCRIPTION=$(markdown2line "$MARKDOWN_PATH")
+
+    CONTAINS_DESCRIPTION=$(grep "post.description" "$INI_PATH")
+    if [ "$CONTAINS_DESCRIPTION" = "" ]; then
+        sed -i "/^post\.summary.*/a \
+        post.description = $DESCRIPTION" "$INI_PATH"
+    else
+        sed -i "s/post.description =.*/post.description = $DESCRIPTION/" "$INI_PATH"
+    fi
+    printf " ✓\n"
+}
+
+for file in "$@"; do
+    insert_description "$file"
+done

package.json

@@ -9,6 +9,7 @@
         "generate:example-tests": "node bin/generate-example-tests.mjs",
         "generate:service": "./bin/create-service-from-template.sh",
         "help": "bat SCRIPTS.md || cat SCRIPTS.md",
+        "insert:description": "./bin/insert-description.sh",
         "publish": "./bin/publish.sh",
         "update:images": "./bin/update-images.sh",
         "test": "echo \"Error: no test specified\" && exit 1",
@@ -41,14 +42,14 @@
         "services/terms-extraction"
     ],
     "dependencies": {
-        "@ezs/analytics": "2.2.1",
-        "@ezs/basics": "2.5.8",
-        "@ezs/core": "3.4.4",
+        "@ezs/analytics": "2.2.2",
+        "@ezs/basics": "2.6.0",
+        "@ezs/core": "3.6.0",
         "@ezs/spawn": "1.4.5",
         "@orangeopensource/hurl": "4.1.0",
         "rest-cli": "1.8.13"
     },
     "devDependencies": {
-        "@types/node": "20.10.4"
+        "@types/node": "20.11.16"
     }
 }

services/terms-extraction/v1/teeft/en.ini

@@ -16,6 +16,7 @@ post.responses.default.content.application/json.example.0.value.4 = specific ter
 post.responses.default.content.application/json.schema.$ref =  #/components/schemas/JSONStream
 post.responses.default.description = Termes extraits du texte envoyé
 post.summary = Extrait des termes du texte en anglais en utilisant Teeft
+post.description = Renvoie les termes les plus spécifiques d'un texte en anglais.  ^MPermet d’avoir une idée de ce dont parle le texte. Idéalement, le texte doit contenir plusieurs paragraphes.^M^MPar défaut `teeft` extrait 5 termes, sauf si la variable `nb` est utilisée.^M^M### Bibliographie^M^MCuxac P., Kieffer N., Lamirel J.C. : *SKEEFT: indexing method taking into account the structure of the document*. 20th Collnet meeting, 5-8 Nov 2019, Dalian, China.
 post.tags.0: terms-extraction
 post.parameters.0.description = Nombre maximal de termes à récupérer
 post.parameters.0.in = query

services/terms-extraction/v1/teeft/fr.ini

@@ -15,6 +15,7 @@ post.responses.default.content.application/json.example.0.value.4 = informations
 post.responses.default.content.application/json.schema.$ref =  #/components/schemas/JSONStream
 post.responses.default.description = Termes extraits du texte envoyé
 post.summary = Extrait des termes du texte en français en utilisant Teeft
+post.description = Renvoie les termes les plus spécifiques d'un texte en français.  ^MPermet d’avoir une idée de ce dont parle le texte. Idéalement, le texte doit contenir plusieurs paragraphes.^M^MPar défaut `teeft` extrait 5 termes, sauf si la variable `nb` est utilisée.^M^M### Bibliographie^M^MCuxac P., Kieffer N., Lamirel J.C. : *SKEEFT: indexing method taking into account the structure of the document*. 20th Collnet meeting, 5-8 Nov 2019, Dalian, China.
 post.tags.0: terms-extraction
 post.parameters.0.description = Nombre maximal de termes à récupérer
 post.parameters.0.in = query

services/terms-extraction/v1/teeft/with-numbers/en.ini

@@ -21,6 +21,7 @@ post.responses.default.content.application/json.example.1.value.3 = 2nd order wa
 post.responses.default.content.application/json.schema.$ref =  #/components/schemas/JSONStream
 post.responses.default.description = Termes extraits du texte envoyé
 post.summary = Extrait des termes du texte en anglais en utilisant Teeft prenant en compte les nombres
+post.description = Extrait les termes les plus pertinents d’un texte en anglais, sans enlever les chiffres.^M^MApplique l’algorithme `teeft`, qui extrait les termes les plus spécifiques d’un texte en anglais.  ^MIl permet d’avoir une idée de ce dont parle le texte. Idéalement, le texte doit contenir plusieurs paragraphes.  ^M^MLa différence avec le service `teeft` classique, est qu’il peut fournir des termes contenant des chiffres (c’est important quand on a des formules chimiques, des grandeurs physiques, …).^M^M### Bibliographie^M^MCuxac P., Kieffer N., Lamirel J.C. : *SKEEFT: indexing method taking into account the structure of the document*. 20th Collnet meeting, 5-8 Nov 2019, Dalian, China.
 post.tags.0: terms-extraction
 post.parameters.0.description = Nombre maximal de termes à récupérer
 post.parameters.0.in = query

services/terms-extraction/v1/teeft/with-numbers/fr.ini

@@ -16,6 +16,7 @@ post.responses.default.content.application/json.example.0.value.4 = informations
 post.responses.default.content.application/json.schema.$ref =  #/components/schemas/JSONStream
 post.responses.default.description = Termes extraits du texte envoyé
 post.summary = Extrait des termes du texte en français en utilisant Teeft prenant en compte les nombres
+post.description = Extrait les termes les plus pertinents d’un texte en français, sans enlever les chiffres.^M^MApplique l’algorithme `teeft`, qui extrait les termes les plus spécifiques d’un texte en français.  ^MIl permet d’avoir une idée de ce dont parle le texte. Idéalement, le texte doit contenir plusieurs paragraphes.  ^M^MLa différence avec le service `teeft` classique, est qu’il peut fournir des termes contenant des chiffres (c’est important quand on a des formules chimiques, des grandeurs physiques, …).^M^M### Bibliographie^M^MCuxac P., Kieffer N., Lamirel J.C. : *SKEEFT: indexing method taking into account the structure of the document*. 20th Collnet meeting, 5-8 Nov 2019, Dalian, China.
 post.tags.0: terms-extraction
 post.parameters.0.description = Nombre maximal de termes à récupérer
 post.parameters.0.in = query

services/terms-extraction/v1_teeft_en.md

@@ -0,0 +1,8 @@
+Renvoie les termes les plus spécifiques d'un texte en anglais.  
+Permet d’avoir une idée de ce dont parle le texte. Idéalement, le texte doit contenir plusieurs paragraphes.
+
+Par défaut `teeft` extrait 5 termes, sauf si la variable `nb` est utilisée.
+
+### Bibliographie
+
+Cuxac P., Kieffer N., Lamirel J.C. : *SKEEFT: indexing method taking into account the structure of the document*. 20th Collnet meeting, 5-8 Nov 2019, Dalian, China.

services/terms-extraction/v1_teeft_fr.md

@@ -0,0 +1,8 @@
+Renvoie les termes les plus spécifiques d'un texte en français.  
+Permet d’avoir une idée de ce dont parle le texte. Idéalement, le texte doit contenir plusieurs paragraphes.
+
+Par défaut `teeft` extrait 5 termes, sauf si la variable `nb` est utilisée.
+
+### Bibliographie
+
+Cuxac P., Kieffer N., Lamirel J.C. : *SKEEFT: indexing method taking into account the structure of the document*. 20th Collnet meeting, 5-8 Nov 2019, Dalian, China.

services/terms-extraction/v1_teeft_with-numbers_en.md

@@ -0,0 +1,10 @@
+Extrait les termes les plus pertinents d’un texte en anglais, sans enlever les chiffres.
+
+Applique l’algorithme `teeft`, qui extrait les termes les plus spécifiques d’un texte en anglais.  
+Il permet d’avoir une idée de ce dont parle le texte. Idéalement, le texte doit contenir plusieurs paragraphes.  
+
+La différence avec le service `teeft` classique, est qu’il peut fournir des termes contenant des chiffres (c’est important quand on a des formules chimiques, des grandeurs physiques, …).
+
+### Bibliographie
+
+Cuxac P., Kieffer N., Lamirel J.C. : *SKEEFT: indexing method taking into account the structure of the document*. 20th Collnet meeting, 5-8 Nov 2019, Dalian, China.

services/terms-extraction/v1_teeft_with-numbers_fr.md

@@ -0,0 +1,10 @@
+Extrait les termes les plus pertinents d’un texte en français, sans enlever les chiffres.
+
+Applique l’algorithme `teeft`, qui extrait les termes les plus spécifiques d’un texte en français.  
+Il permet d’avoir une idée de ce dont parle le texte. Idéalement, le texte doit contenir plusieurs paragraphes.  
+
+La différence avec le service `teeft` classique, est qu’il peut fournir des termes contenant des chiffres (c’est important quand on a des formules chimiques, des grandeurs physiques, …).
+
+### Bibliographie
+
+Cuxac P., Kieffer N., Lamirel J.C. : *SKEEFT: indexing method taking into account the structure of the document*. 20th Collnet meeting, 5-8 Nov 2019, Dalian, China.