From c8d7cc4f0b49eabbe4fd650814e9d78036b0f1a3 Mon Sep 17 00:00:00 2001 From: viennet Date: Thu, 30 Dec 2021 09:58:58 +0100 Subject: [PATCH] ajouts et corrections --- docs/GuideConfig.md | 1 + docs/GuideDeveloppeurs.md | 77 ++++++++++++++++++++------------------- docs/ScoDoc9API.md | 31 ++++++++++++++-- 3 files changed, 67 insertions(+), 42 deletions(-) diff --git a/docs/GuideConfig.md b/docs/GuideConfig.md index 97f5fb8..7eee76d 100644 --- a/docs/GuideConfig.md +++ b/docs/GuideConfig.md @@ -135,6 +135,7 @@ Commands: clear-cache Clear ScoDoc cache This cache (currently... create-dept Create new departement create-role Create a new role + delete-role Delete a role delete-dept Delete existing departement dumphelp edit-role Add [-a] and/or remove [-r] a permission... diff --git a/docs/GuideDeveloppeurs.md b/docs/GuideDeveloppeurs.md index bd0f6d7..19e0b4f 100644 --- a/docs/GuideDeveloppeurs.md +++ b/docs/GuideDeveloppeurs.md @@ -56,7 +56,7 @@ Exemple: ### Git -Le dépot est +Le dépôt est La branche `master` est celle de ScoDoc 9. La branche `Scodoc7` est l'ancienne (jusqu'à septembre 2021) version en production. @@ -125,7 +125,7 @@ Note pour travailler sur VirtualBox: L'essentiel des remarques/procédures de cette section vise à obtenir une relecture facile des modifications: -* Eviter les modifications de forme sans substance sémantique. L'utilisation de blackify permet de normaliser la présentation du code +* Éviter les modifications de forme sans substance sémantique. L'utilisation de [`black`](https://black.readthedocs.io/) permet de normaliser la présentation du code. * Avoir un nombre d'étapes de validation faible (idéalement un seul commit pour les PR courantes (peu volumineuses) @@ -133,34 +133,34 @@ L'essentiel des remarques/procédures de cette section vise à obtenir une relec ##### Manipulations -Les manipulations sont décrites selons 4 phases du développement: l'installation, la mise en place, le suivi, la livraison. +Les manipulations sont décrites selon 4 phases du développement: l'installation, la mise en place, le suivi, la livraison. ###### l'installation -Il est pratique d'avoir en ligne les deux dépot git distant que vous pouvez utiliser: votre dépot personnel (`https://scodoc.org/git//.git`) -et le dépot officiel (`https://scodoc.org/git/ScoDoc/ScoDoc.git`) +Il est pratique d'avoir en ligne les deux dépôt git distant que vous pouvez utiliser: votre dépôt personnel (`https://scodoc.org/git//.git`) +et le dépôt officiel (`https://scodoc.org/git/ScoDoc/ScoDoc.git`) -pour ajouter une référence (et lui donner un nom) vers un depot distant, envoyez la commande: +pour ajouter une référence (et lui donner un nom) vers un dépôt distant, envoyez la commande: -```git remote add nom_remote https://scodoc.org/git/ScoDoc/.git``` +```git remote add nom_remote https://scodoc.org/git/ScoDoc/.git``` -Par la suite vous aurez donc une référence vers votre dépôt personnel (`perso`) et une référence vers le depot officiel (`officiel`). L'un des deux -si vous avez iniitalement cloné l'un des deux dépots, la référence vers celui-ci existe et a pour nom òrigin` +Par la suite vous aurez donc une référence vers votre dépôt personnel (`perso`) et une référence vers le dépôt officiel (`officiel`). L'un des deux +si vous avez initialement cloné l'un des deux dépôts, la référence vers celui-ci existe et a pour nom `origin`. -la commande vous exposant tous les dépots connus est : +La commande vous exposant tous les dépôts connus est : `git remote -v` ##### Mise en place -l'objectf de ce paragraphe est de créer une branche locale basée sur le master du dépot officiel et bien sur de lui donner un nom. +L'objectif de ce paragraphe est de créer une branche locale basée sur le master du dépôt officiel et bien sur de lui donner un nom. -pour cela (attention cela va ecraser les éventuels fichiers modifiés) +pour cela (attention cela va écraser les éventuels fichiers modifiés) ``` git reset --hard officiel/master git checkout -b ma_modif ``` -A partir de la vous pouvez modifier, tester, developper, commit +À partir de la vous pouvez modifier, tester, développer, commit. ##### Suivi @@ -168,11 +168,11 @@ Si votre développement prend plusieurs jours, il est probable que la branche pr Pour garder la cohérence, il est nécessaire de réintégrer en local les modifications de la branche principale. Ceci peut se faire de deux façons. -une fusion (merge) applique toutes les modifs en une seul commit). c est la méthode courament utilisée + - Une fusion (`merge`) applique toutes les modifications en une seul commit). C'est la méthode couramment utilisée -un rebase rejoue tous les commits de la nouvelle branche par dessus l'état le plus à jour de la branche principal (il en résulte un historique plus linéaire) + - Un `rebase` rejoue tous les commits de la nouvelle branche par dessus l'état le plus à jour de la branche principal (il en résulte un historique plus linéaire) -les commandes git correspondantes: +Les commandes git correspondantes: ``` git fetch officiel @@ -186,19 +186,20 @@ git rebase officiel/merge ##### La livraison -Ca y est. vous avez terminé le développment. IL n'y a plus qu'à demander l'intégration. Ceci se fait en plusieurs étapes (vous êtes bien sur toujours sur la branche locale `ma_modif`) +Ça y est. vous avez terminé le développement. IL n'y a plus qu'à demander l'intégration. Ceci se fait en plusieurs étapes (vous êtes bien sûr toujours sur la branche locale `ma_modif`). -###### Etape 1 : faire l'inventaire des fichiers impliqués +###### Étape 1 : faire l'inventaire des fichiers impliqués ``` git fetch officiel/master git diff --name-only officiel/master ``` -###### Etape 2 : passer black sur les fichiers modifiés -Cette étape est automatique avec les bons réglages sous VSCode (pas trouvé l'équivallent sous pyCharm) +###### Étape 2 : passer black sur les fichiers modifiés -à défaut les lignes suivantes réalisent le même travail +Cette étape est automatique avec les bons réglages sous VSCode (pas trouvé l'équivalent sous *pyCharm*) + +À défaut les lignes suivantes réalisent le même travail: ``` for fn in $(git diff --name-only officiel/master) @@ -214,23 +215,23 @@ git diff officiel/master app/fichier.py ``` Utilisateurs Windows: -Vérifiez bien que les réglages de fin de ligne suivant bien les règles linux (pas de CR ou \r en fin de ligne juste les LF \n). -Le cas écéheant réglez votre IDE pour cela +Vérifiez bien que les réglages de fin de ligne suivant bien les règles Linux (pas de CR ou `\r` en fin de ligne juste les LF `\n`). +Le cas échéant réglez votre IDE pour cela -A ce niveau là vous n'avez dans votre branche locales que les différences nécessaires à votre correctif. +À ce niveau là vous n'avez dans votre branche locales que les différences nécessaires à votre correctif. -###### Etape 3: résumez tous les commits depuis le point de divergence en un seul commit +###### Étape 3: résumez tous les commits depuis le point de divergence en un seul commit Repérez le point de divergence de votre branche locale avec officiel/master -(normalement git merge-base ma_branche officiel/master) +(normalement `git merge-base ma_branche officiel/master`) -demander un rebase interactif depuis ce point +Demander un `rebase` interactif depuis ce point: ``` git rebase -i $(git merge-base HEAD officiel/master) ``` -vous devez obtenir dans un éditeur de texte la liste des commits opéré depuis le début du développment sou scette forme (c'est un exemple le nombre de lignes peut varier) +Vous devez obtenir dans un éditeur de texte la liste des commits opéré depuis le début du développement sous cette forme (c'est un exemple le nombre de lignes peut varier) ``` pick eb8cbec modif 1 @@ -267,33 +268,33 @@ pick 83eb79e modif 2 ``` vous pouvez réorganiser tous les commits (changer l'ordre, fusionner) en changeant la commande pick au début de chaque ligne -l idée ici est de fusionner toutes les lignes avec la première en remplaçant le 'pick' à partir de la ligne 2 par 'fixup'. -optionnellement, vous pouvez reformuler le message de commit (commande 'reword' sur la première ligne) +l idée ici est de fusionner toutes les lignes avec la première en remplaçant le 'pick' à partir de la ligne 2 par `fixup`. +optionnellement, vous pouvez reformuler le message de commit (commande `reword` sur la première ligne). -vous construirez par exemple: +Vous construirez par exemple: ``` reword eb8cbec Correctif: Api - gestion des formation fixup 83eb79e modif 2 ... ``` -Quand vous sortez de l'éditeur git effectue toutes les opérations demandées +Quand vous sortez de l'éditeur, git effectue toutes les opérations demandées -A ce niveau là de la procédure: +À ce niveau là de la procédure: * vous avez un seul commit pour l'ensemble du correctif proposé -* toutes les différeences entre officiel/master et votre branche locale sont signifiantes +* toutes les différences entre officiel/master et votre branche locale sont signifiantes -###### Etape 4: -vous pouvez maintenant pousser votre branche locale sur votre depot personnel (vers une branche de même nom): +###### Étape 4: +Vous pouvez maintenant pousser votre branche locale sur votre dépôt personnel (vers une branche de même nom): ``` git push --set-upstream perso ma_branche ``` -Si vous avez déjà fait cette opération auparavent il est possible que le push soit refusé (car le rebase à modifié des commits qui avaient déjà été poussés). -Dans ce cas l'option `--force` du push vous permete de passer outre, mais assurez-vous avant d'être le seul à travailler sur cette branche. +Si vous avez déjà fait cette opération auparavant il est possible que le push soit refusé (car le rebase a modifié des commits qui avaient déjà été poussés). +Dans ce cas l'option `--force` du push vous permette de passer outre, mais assurez-vous avant d'être le seul à travailler sur cette branche. ###### Etape 5: La dernière étape se passe sur le site scodoc.org/git diff --git a/docs/ScoDoc9API.md b/docs/ScoDoc9API.md index 6bc9b75..892cba5 100644 --- a/docs/ScoDoc9API.md +++ b/docs/ScoDoc9API.md @@ -63,13 +63,34 @@ La documentation ci-dessous concerne la **future** version De ScoDoc. Elle sera accessible à l'adresse: https://scodoc.monsite.tld/ScoDoc/api/fonction ### Authentification - TODO décrire procédure d'authentification et tokens jwt. -Lors de votre authentification (_connection avec login et mdp_) à Scodoc, il vous sera attribué un token jwt (_généré automatiquement_) vous permettant d'utiliser l'api suivant les droits correspondant à votre session. +Lors de votre authentification (_connection avec login et mdp_) à Scodoc, il +vous sera attribué un jeton (token jwt _généré automatiquement_) vous permettant +d'utiliser l'api suivant les droits correspondant à votre session. +Pour obtenir le jeton, il faut un compte sur ScoDoc (`user_name`et `password`). +Les autorisations et rôles sont gérés exactement comme pour l'application. + +Exemple avec `curl` (un outil en ligne de commande présent sur la plupart des +systèmes): + + curl -u user_name:password --request POST https://SERVEUR/ScoDoc/api/tokens + +où `SERVEUR` est l'adresse (IP ou nom) de votre serveur. +La réponse doit ressembler à ceci: +``` +{ + "token": "LuXXxk+i74TXYZZl8MulgbiCGmVHXXX" +} +``` + +Vous trouverez dans `/opt/scodoc/tests/api/exemple-api-basic.py` un exemple +complet en python d'interrogation de l'API. ### Codes HTTP -Chaque appel à l'API donne lieu à une réponse retournant un code spécifique en fonction du résultat obtenu. L'analyse de ce code vous permet de vous assurer que la requête a été traitée avec succès. +Chaque appel à l'API donne lieu à une réponse retournant un code spécifique en +fonction du résultat obtenu. L'analyse de ce code vous permet de vous assurer +que la requête a été traitée avec succès. Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succès par nos serveurs. @@ -87,7 +108,9 @@ Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succ ## Départements * **`departements`** * **Méthode:** GET - * **Paramètres:** `viewable` (optionnel, si faux liste aussi les départements non accessibles à l'utilisateur courant), `format` (json, xml) + * **Paramètres:** `viewable` (optionnel, si faux liste aussi les + départements non accessibles à l'utilisateur courant), `format` (json, + xml) * **Routes:** `/api/departements` * **Exemple d'utilisation:** `/api/departements` * **Résultat:** Liste des id de départements.