DocAssiduites/docs/GuideDeveloppeurs.md

160 lines
4.7 KiB
Markdown

# Documentation pour les développeurs ScoDoc
Informations pour les développeurs souhaitant étendre ou modifier ScoDoc.
Pour le développement de logiciels externes, [utiliser l'API](ScoDoc9API.md).
Accès à la [plate-forme Gitea](https://scodoc.org/git).
## Informations générales
Les échanges se font sur Discord, voir [contacts](Contact.md). Il y a un serveur
Discord ouvert sur invitation aux développeur actifs. Contacter Emmanuel Viennet
(`@emm`).
- [Développement ScoDoc: Introduction](DevInternals.md)
- [Utilisation de git](DevGit.md)
- [Définition des cursus](DevCursus.md)
- [Générer de nouveaux formats de bulletins PDF](ApiGenerationBulletinsPdf.md)
- [Gestion des jurys BUT](DevJuryBUT.md)
- [API](ScoDoc9API.md) : API pour interfaçage avec d'autres applications
- Notes diverses (caduques, pour mémoire)
- [Très anciennes 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 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'est nettement amélioré avec ScoDoc 9 (respect PEP 8).
Le code DOIT être formaté avec [`black`](https://black.readthedocs.io/) avant
tout commit (configurez votre éditeur pour appeler `black` à l'enregistrement).
#### Documentation
On pourra adopter le style "Google": <https://google.github.io/styleguide/pyguide.html#383-functions-and-methods>
Exemple:
```py
"""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
Voir [la page sur git et ScoDoc](DevGit.md)
## Tests et tests unitaires
Voir [TestsScoDoc](TestsScoDoc.md)
## Cache Redis
Certains objets couteux à calculer sont cachés. Depuis 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_),
affiche toutes les 3 secondes.
- `flask clear-cache` efface le cache Redis.
## Re-création du virtualenv
ScoDoc est livré avec un "virtualenv", qui contient tous les modules python
nécessaires. Il se trouve sous `/opt/scodoc/venv`.
Si vous souhaitez repartir de zéro, tester de nouvelles versions de certaines
bibliothèques, ou autres expériences de ce genre, vous pouvez le récréer ainsi:
```bash
# en tant qu'utilisateur scodoc
cd /opt/scodoc
/bin/rm -rf venv # ou mv ...
python3 -m venv venv
source venv/bin/activate
pip install wheel
```
Puis soit vous installez les versions "officielles" (testées)
```bash
pip install -r requirements-3.9.txt
```
Soit vous prenez les versions les plus à jour disponibles. Une façon rapide de
faire ceci est:
```bash
cut -d= -f 1 requirements-3.11.txt | xargs pip install
```
à adapter selon vos objectifs.
Pour régénérer le fichier indiquant la liste des paquets:
```bash
pip freeze > requirements-3.11.txt
```
Enfin, pour mettre à jour les paquets pip, il faut dégeler les versions (unpin)
puis upgrader et re-générer le fichier, comme suit:
```bash
cp requirements-3.11.txt requirements.text
sed -i 's/[~=]=/>=/' requirements.txt
pip install -U -r requirements.txt
pip freeze > requirements-new.txt
# et si tout va bien
mv requirements-new.txt requirements-3.11.txt
```
Note: la mise à jour par `apt` recrée le virtualenv à chaque fois.
## Roadmap
* [voir les tickets](https://scodoc.org/git/viennet/ScoDoc/issues)
!!! note "Voir aussi"
- [Conventions de codage](DevConventions.md)
- [API ScoDoc 9](ScoDoc9API.md)
- [Guide installation](GuideInstallDebian11.md)
- [Gestion des utilisateurs](AdminUsers.md)
- [Guide administrateur ScoDoc](GuideAdminSys.md)
- [FAQ](FAQ.md)
- [Contacts](Contact.md)