forked from ScoDoc/DocScoDoc
160 lines
4.7 KiB
Markdown
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://git.scodoc.org).
|
|
|
|
## 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'une 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.11.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.txt
|
|
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://git.scodoc.org/viennet/ScoDoc/issues)
|
|
|
|
|
|
!!! note "Voir aussi"
|
|
|
|
- [Conventions de codage](DevConventions.md)
|
|
- [API ScoDoc 9](ScoDoc9API.md)
|
|
- [Guide installation](GuideInstallDebian12.md)
|
|
- [Gestion des utilisateurs](AdminUsers.md)
|
|
- [Guide administrateur ScoDoc](GuideAdminSys.md)
|
|
- [FAQ](FAQ.md)
|
|
- [Contacts](Contact.md) |