forked from ScoDoc/DocScoDoc
152 lines
4.8 KiB
Markdown
152 lines
4.8 KiB
Markdown
# Documentation pour les développeurs ScoDoc
|
|
|
|
|
|
Informations pour les développeurs souhaitant étendre ou modifier ScoDoc.
|
|
|
|
## Informations générales
|
|
|
|
* S'abonner aux [listes de diffusion](ListesDeDiffusion.md). Il y a aussi
|
|
un serveur Discord ouvert sur invitation aux développeur actifs. Contacter Emmanuel.
|
|
* [Générer de nouveaux formats de bulletins PDF](ApiGenerationBulletinsPdf.md)
|
|
* [Créer de nouveaux types de "parcours"](ApiCreationParcours.md)
|
|
* [API](ScoDocAPI.md) : API JSON ou XML pour interfaçage avec d'autres applications
|
|
* Notes diverses
|
|
* [Discussions pour la future gestion des absences](IdeesGestionAbsences.md)
|
|
* [Anciennes discussions sur la gestion des plannings](IdeesGestionPlannings.md)
|
|
|
|
|
|
## Développer sur ScoDoc
|
|
|
|
Quelques conseils, indications et mémos pour les développeurs sur ScoDoc version 9.
|
|
|
|
### Installation d'un serveur de développement
|
|
[Quelques conseils mouvants pour configurer votre serveur de développement](ConseilServeurDev.md)
|
|
|
|
### Style et formatage du code
|
|
L'ancienneté de la base de code a rendu le style un peu incohérent, mais cela
|
|
s'améliore avec ScoDoc 9 (respect PEP 8).
|
|
|
|
Le code doit être formatté avec [`black`](https://black.readthedocs.io/) avant
|
|
tout commit (configurez votre éditeur pour appeler `black` à l'enregistrement).
|
|
|
|
#### Documentation
|
|
On adoptera le style "Google": <https://google.github.io/styleguide/pyguide.html#383-functions-and-methods>
|
|
|
|
Exemple:
|
|
"""Description résumée de la fonction
|
|
|
|
blah blah sur la fonction
|
|
|
|
Args:
|
|
table_handle: An open smalltable.Table instance.
|
|
keys: A sequence of strings representing the key of each table
|
|
row to fetch. String keys will be UTF-8 encoded.
|
|
require_all_keys: Optional; If require_all_keys is True only
|
|
rows with values set for all keys will be returned.
|
|
|
|
Returns:
|
|
A dict mapping keys to the corresponding table row data
|
|
fetched. Each row is represented as a tuple of strings. For
|
|
example:
|
|
|
|
{b'Serak': ('Rigel VII', 'Preparer'),
|
|
b'Zim': ('Irk', 'Invader'),
|
|
b'Lrrr': ('Omicron Persei 8', 'Emperor')}
|
|
"""
|
|
|
|
### Git
|
|
|
|
Le dépot est <https://scodoc.org/git/viennet/ScoDoc>
|
|
|
|
La branche `master` est celle de ScoDoc 9 (pas encore en production). La branche
|
|
`Scodoc7` est l'ancienne (actuelle jusqu'à septembre 2021) en production.
|
|
|
|
Ci-dessous quelques pense-bête qui peuvent servir.
|
|
#### Hot fixes (internes)
|
|
|
|
Pour les développeurs internes (écriture sur le dépot master), un exemple basique:
|
|
|
|
# Créer une branche
|
|
# si besoin (travail en cours), utiliser git stash avant
|
|
git checkout master
|
|
git branch hotfix
|
|
git checkout hotfix
|
|
... dev, test ...
|
|
git add ...
|
|
git commit -m "fixed ..."
|
|
git checkout master
|
|
git merge hotfix
|
|
git branch -d hotfix
|
|
# publication
|
|
|
|
# éventuellement: git stash pop
|
|
|
|
#### Mettre à jour votre branche
|
|
|
|
Vous travaillez dans votre branche `ma_branche`. Pour lui appliquer les mises à jour de `master` (remote):
|
|
|
|
git pull origin master
|
|
|
|
#### Commandes utiles, en vrac
|
|
|
|
* `git log -L:fonction_python:fichier.py`
|
|
* Commits locaux: `git log @{u}..`
|
|
|
|
#### Refactoring
|
|
|
|
Lint tous les fichiers modifiés:
|
|
|
|
git status | grep modified | grep .py | awk '{print $2}' | xargs pylint -E
|
|
|
|
Restore les modes au besoin (SAMBA les changent parfois):
|
|
|
|
git diff -p -R --no-color | grep -E "^(diff|(old|new) mode)" --color=never | git apply
|
|
|
|
Affiche les variables non définies dans un fichier:
|
|
|
|
pylint --disable=all -e E sco_parcours_dut.py | grep undefined-variable | awk '{print $4;}' | sort | uniq | tr -d \'
|
|
|
|
Prépare un sed pour renommer les variables non définies:
|
|
|
|
for f in *.py
|
|
do
|
|
pylint --disable=all -e E "$f" | grep undefined-variable | awk '{print "sed -i .bak s/"$4"/scu."$4"/ '$f'";}' | sort | uniq | tr -d \'
|
|
done
|
|
|
|
Note pour travailler sur VirtualBox:
|
|
|
|
addgroup scodoc vboxsf
|
|
|
|
### Tests
|
|
|
|
Voir [TestsScoDoc](TestsScoDoc.md)
|
|
|
|
## Cache Redis
|
|
|
|
Certains objets couteux à calculer sont cachés. Depuyis ScoDoc 9, on utilise Redis, via `flask-caching`.
|
|
|
|
Au besoin, mémo:
|
|
|
|
- client ligne de commande: `https://redis.io/topics/rediscli`
|
|
|
|
- afficher les clés: `redis-cli KEYS '*'`
|
|
|
|
- `redis-cli TTL key` affiche le TTL d'un clé, -1 si infini.
|
|
|
|
- `redis-cli -r -1 -i 3 KEYS '*_NT_*'` surveille certaines clés (ici _NT_), affche toutes les 3 secondes.
|
|
|
|
- `flask clear-cache` efface le cache Redis.
|
|
|
|
|
|
## Roadmap
|
|
Sujets **prioritaires** en 2021:
|
|
|
|
- modernisation du code: Flask, Python 3: achevé août 2021
|
|
|
|
- prise en compte du Bachelor (BUT): SAÉ, suivi compétences, validations des blocs, UE, semestres selon la cadrage et l'arêté Licence Pro 2020.
|
|
|
|
- Redéfinition API et interface mobile simplifiée.
|
|
|
|
Autres sujets:
|
|
- [voir les tickets](https://scodoc.org/git/viennet/ScoDoc/issues)
|