DocScoDoc/docs/GuideDeveloppeurs.md

160 lines
4.7 KiB
Markdown
Raw Normal View History

2020-09-21 16:30:27 +02:00
# 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).
2024-05-27 12:58:01 +02:00
Accès à la [plate-forme Gitea](https://git.scodoc.org).
2021-01-28 09:47:27 +01:00
## 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)
2023-07-04 15:59:43 +02:00
- [Gestion des jurys BUT](DevJuryBUT.md)
- [API](ScoDoc9API.md) : API pour interfaçage avec d'autres applications
2023-07-04 15:59:43 +02:00
- 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)
2022-11-13 16:06:33 +01:00
2021-08-22 08:14:55 +02:00
## Développer sur ScoDoc
2021-01-28 09:47:27 +01:00
2021-09-14 12:31:16 +02:00
Quelques conseils, indications et mémos pour les développeurs sur ScoDoc version 9.
2021-01-28 09:47:27 +01:00
2021-02-01 19:55:50 +01:00
### Installation d'un serveur de développement
2022-11-13 16:06:33 +01:00
[Quelques conseils pour configurer votre serveur de développement](ConseilServeurDev.md)
2021-02-01 19:55:50 +01:00
2021-01-28 09:47:27 +01:00
### Style et formatage du code
2022-11-13 16:06:33 +01:00
2023-07-04 15:59:43 +02:00
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).
2021-01-28 09:47:27 +01:00
Le code DOIT être formaté avec [`black`](https://black.readthedocs.io/) avant
2021-09-14 12:31:16 +02:00
tout commit (configurez votre éditeur pour appeler `black` à l'enregistrement).
2021-01-28 09:47:27 +01:00
#### Documentation
2022-11-13 16:06:33 +01:00
On pourra adopter le style "Google": <https://google.github.io/styleguide/pyguide.html#383-functions-and-methods>
2021-01-28 09:47:27 +01:00
Exemple:
2023-03-10 11:32:27 +01:00
```py
2021-01-28 09:47:27 +01:00
"""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')}
"""
2023-03-10 11:32:27 +01:00
```
2021-01-28 09:47:27 +01:00
### Git
Voir [la page sur git et ScoDoc](DevGit.md)
2021-12-21 15:56:23 +01:00
2021-12-30 13:40:30 +01:00
## Tests et tests unitaires
2021-08-22 08:14:55 +02:00
Voir [TestsScoDoc](TestsScoDoc.md)
## Cache Redis
Certains objets couteux à calculer sont cachés. Depuis ScoDoc 9, on utilise
Redis, via `flask-caching`.
2021-08-22 08:14:55 +02:00
Au besoin, mémo:
2022-11-13 16:06:33 +01:00
- client ligne de commande: `https://redis.io/topics/rediscli`
2021-08-22 08:14:55 +02:00
2022-11-13 16:06:33 +01:00
- afficher les clés: `redis-cli KEYS '*'`
2021-08-22 08:14:55 +02:00
2024-01-26 11:53:55 +01:00
- `redis-cli TTL key` affiche le TTL d'une clé, -1 si infini.
2021-08-22 08:14:55 +02:00
2022-11-13 16:06:33 +01:00
- `redis-cli -r -1 -i 3 KEYS '*_NT_*'` surveille certaines clés (ici _NT_),
affiche toutes les 3 secondes.
2021-08-22 08:14:55 +02:00
2022-11-13 16:06:33 +01:00
- `flask clear-cache` efface le cache Redis.
2021-01-28 09:47:27 +01:00
2022-01-08 00:58:33 +01:00
## Re-création du virtualenv
ScoDoc est livré avec un "virtualenv", qui contient tous les modules python
2022-11-13 16:06:33 +01:00
nécessaires. Il se trouve sous `/opt/scodoc/venv`.
2022-01-08 00:58:33 +01:00
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:
2022-11-13 16:06:33 +01:00
2022-01-08 00:58:33 +01:00
```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
```
2022-11-13 16:06:33 +01:00
2022-01-08 00:58:33 +01:00
Puis soit vous installez les versions "officielles" (testées)
2022-11-13 16:06:33 +01:00
2023-03-10 11:32:27 +01:00
```bash
2024-08-15 21:30:35 +02:00
pip install -r requirements-3.11.txt
2022-01-08 00:58:33 +01:00
```
2022-11-13 16:06:33 +01:00
Soit vous prenez les versions les plus à jour disponibles. Une façon rapide de
2022-01-08 00:58:33 +01:00
faire ceci est:
2022-11-13 16:06:33 +01:00
2022-01-08 00:58:33 +01:00
```bash
2023-07-25 08:53:38 +02:00
cut -d= -f 1 requirements-3.11.txt | xargs pip install
2022-01-08 00:58:33 +01:00
```
2023-03-10 11:32:27 +01:00
2022-01-08 00:58:33 +01:00
à adapter selon vos objectifs.
2022-11-13 16:06:33 +01:00
2022-01-08 00:58:33 +01:00
Pour régénérer le fichier indiquant la liste des paquets:
2022-11-13 16:06:33 +01:00
2022-01-08 00:58:33 +01:00
```bash
2023-07-25 08:53:38 +02:00
pip freeze > requirements-3.11.txt
2022-01-08 00:58:33 +01:00
```
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
2024-08-15 21:30:35 +02:00
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
```
2022-01-08 00:58:33 +01:00
Note: la mise à jour par `apt` recrée le virtualenv à chaque fois.
2021-01-28 09:47:27 +01:00
2021-01-29 13:41:40 +01:00
## Roadmap
2024-05-27 12:58:01 +02:00
* [voir les tickets](https://git.scodoc.org/viennet/ScoDoc/issues)
2021-01-29 13:41:40 +01:00
2023-03-10 11:32:27 +01:00
!!! note "Voir aussi"
2023-12-12 13:39:20 +01:00
- [Conventions de codage](DevConventions.md)
- [API ScoDoc 9](ScoDoc9API.md)
2024-05-30 15:26:44 +02:00
- [Guide installation](GuideInstallDebian12.md)
- [Gestion des utilisateurs](AdminUsers.md)
- [Guide administrateur ScoDoc](GuideAdminSys.md)
2023-03-10 11:32:27 +01:00
- [FAQ](FAQ.md)
- [Contacts](Contact.md)