DocScoDoc/docs/GuideDeveloppeurs.md

# 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)