ScoDoc/DocScoDoc
7
2
Fork 10
Code Issues 1 Pull Requests 1 Projects Releases Wiki Activity

ajouts et corrections

Browse Source
This commit is contained in:
Emmanuel Viennet 2021-12-30 09:58:58 +01:00
parent 3dd03f9b7d
commit c8d7cc4f0b
3 changed files with 67 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/GuideConfig.md
View File

@ -135,6 +135,7 @@ Commands:
clear-cache Clear ScoDoc cache This cache (currently... clear-cache Clear ScoDoc cache This cache (currently...
create-dept Create new departement create-dept Create new departement
create-role Create a new role create-role Create a new role
delete-role Delete a role
delete-dept Delete existing departement delete-dept Delete existing departement
dumphelp dumphelp
edit-role Add [-a] and/or remove [-r] a permission... edit-role Add [-a] and/or remove [-r] a permission...

77
docs/GuideDeveloppeurs.md
View File

@ -56,7 +56,7 @@ Exemple:
### Git ### Git
Le dépot est <https://scodoc.org/git/viennet/ScoDoc> Le dépôt est <https://scodoc.org/git/viennet/ScoDoc>
La branche `master` est celle de ScoDoc 9. La branche `Scodoc7` est l'ancienne La branche `master` est celle de ScoDoc 9. La branche `Scodoc7` est l'ancienne
(jusqu'à septembre 2021) version en production. (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: 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) * 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 ##### 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 ###### 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/<user>/<depot>.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/<user>/<dépôt>.git`)
et le dépot officiel (`https://scodoc.org/git/ScoDoc/ScoDoc.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/<depot>.git``` ```git remote add nom_remote https://scodoc.org/git/ScoDoc/<dépôt>.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 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 iniitalement cloné l'un des deux dépots, la référence vers celui-ci existe et a pour nom òrigin` 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` `git remote -v`
##### Mise en place ##### 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 reset --hard officiel/master
git checkout -b ma_modif 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 ##### 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. 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 git fetch officiel
@ -186,19 +186,20 @@ git rebase officiel/merge
##### La livraison ##### 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 fetch officiel/master
git diff --name-only 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) for fn in $(git diff --name-only officiel/master)
@ -214,23 +215,23 @@ git diff officiel/master app/fichier.py
``` ```
Utilisateurs Windows: 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). 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 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 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) 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 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 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'. 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) 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 reword eb8cbec Correctif: Api - gestion des formation
fixup 83eb79e modif 2 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é * 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: ###### Étape 4:
vous pouvez maintenant pousser votre branche locale sur votre depot personnel (vers une branche de même nom): 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 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). 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 permete de passer outre, mais assurez-vous avant d'être le seul à travailler sur cette branche. 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 ###### Etape 5: La dernière étape se passe sur le site scodoc.org/git

31
docs/ScoDoc9API.md
View File

@ -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 Elle sera accessible à l'adresse: https://scodoc.monsite.tld/ScoDoc/api/fonction
### Authentification ### 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 ### 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. 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 ## Départements
* **`departements`** * **`departements`**
* **Méthode:** GET * **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` * **Routes:** `/api/departements`
* **Exemple d'utilisation:** `/api/departements` * **Exemple d'utilisation:** `/api/departements`
* **Résultat:** Liste des id de départements. * **Résultat:** Liste des id de départements.