forked from ScoDoc/DocScoDoc
MAJ conventions codage
This commit is contained in:
parent
5f44559b76
commit
8e5f8684f7
@ -16,20 +16,22 @@ Pour les nouveaux codes, respecter les principes suivants:
|
|||||||
conduit à dupliquer du code (qui existe en général dans le serveur) et
|
conduit à dupliquer du code (qui existe en général dans le serveur) et
|
||||||
augmente les coûts de maintenance.
|
augmente les coûts de maintenance.
|
||||||
|
|
||||||
## Formatage du code
|
## Conventions de codage
|
||||||
|
|
||||||
|
### Formatage du code
|
||||||
|
|
||||||
- l'usage de **[black](https://black.readthedocs.io/en/stable/)** est obligatoire
|
- l'usage de **[black](https://black.readthedocs.io/en/stable/)** est obligatoire
|
||||||
- l'usage de pylint et mypy est fortement recommandé
|
- l'usage de pylint et mypy est fortement recommandé
|
||||||
- Pour le code JS, indentation avec 2 espaces (sous VS Code, utiliser *Prettier*).
|
- Pour le code JS, indentation avec 2 espaces (sous VS Code, utiliser *Prettier*).
|
||||||
|
|
||||||
## Conventions standard Python
|
### Conventions standard Python
|
||||||
|
|
||||||
On se tient à la PEP8, c'est à dire en résumé:
|
On se tient à la PEP8, c'est à dire en résumé:
|
||||||
`UneClasse`, `une_fonction`, `_une_fonction_privee`, `une_variable`, `UNE_CONSTANTE_GLOBALE`.
|
`UneClasse`, `une_fonction`, `_une_fonction_privee`, `une_variable`, `UNE_CONSTANTE_GLOBALE`.
|
||||||
|
|
||||||
Les noms de fichiers sont en minuscules sans accents ni espaces, `comme_ceci.py`.
|
Les noms de fichiers sont en minuscules sans accents ni espaces, `comme_ceci.py`.
|
||||||
|
|
||||||
## Annotations de type
|
### Annotations de type (typehints)
|
||||||
|
|
||||||
On annote les paramètres et résultats des fonctions.
|
On annote les paramètres et résultats des fonctions.
|
||||||
|
|
||||||
@ -40,9 +42,9 @@ def _upload_justificatif_files(
|
|||||||
...
|
...
|
||||||
```
|
```
|
||||||
|
|
||||||
## Vues et templates
|
## Pages et templates
|
||||||
|
|
||||||
Les vues utilisent un template *Jinja*, fichier avec extension j2.
|
Les vues utilisent un template *Jinja2*, fichier avec extension j2.
|
||||||
|
|
||||||
On s'astreint, sauf cas particulier, à un nommage identique de la route, la vue et du template.
|
On s'astreint, sauf cas particulier, à un nommage identique de la route, la vue et du template.
|
||||||
|
|
||||||
@ -53,10 +55,69 @@ def un_exemple(...):
|
|||||||
return render_template(".../un_exemple.j2")
|
return render_template(".../un_exemple.j2")
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Le template aura typiquement avec la structure suivante:
|
||||||
|
|
||||||
|
```jinja
|
||||||
|
{% extends "sco_page.j2" %}
|
||||||
|
|
||||||
|
{% block app_content %}
|
||||||
|
<h1>Titre</h1>
|
||||||
|
{% endblock app_content %}
|
||||||
|
```
|
||||||
|
|
||||||
|
Pour les pages dans un semestre (avec barre menu etc.), on utilisera `<h2>` au
|
||||||
|
lieu de `<h1>`.
|
||||||
|
|
||||||
|
### Templates habituels
|
||||||
|
|
||||||
|
Les templates suivants sont les plus utilisés pour les pages:
|
||||||
|
|
||||||
|
- `base.j2` pages hors département (accueil, configuration, ...)
|
||||||
|
|
||||||
|
- `sco_page.j2` page standard dans un formsemestre: avec sidebar et barre de
|
||||||
|
menu du semestre.
|
||||||
|
|
||||||
|
- `sco_dept_page.j2` page dans un département (avec sidebar) mais sans formsemestre (pas de
|
||||||
|
barre de menu)
|
||||||
|
|
||||||
|
### Constantes définies dans les templates ScoDoc
|
||||||
|
|
||||||
|
Le `context_processor` `inject_sco_utils()` ajoute des objets pour accès à tous
|
||||||
|
les templates ScoDoc:
|
||||||
|
|
||||||
|
- `scu` : le module `sco_utils.py` (diverses fonctions utilitaires et variables
|
||||||
|
de config.)
|
||||||
|
- `sco` : des données sur le contexte, notamment les préférences, le
|
||||||
|
formsemestre et l'étudiant courants (resp. `sco.formsemestre` et `sco.etud`)
|
||||||
|
|
||||||
|
### Appel d'un template page
|
||||||
|
|
||||||
|
Pour mémoire, l'appel d'un template dans une vue se fait ainsi:
|
||||||
|
|
||||||
|
```py
|
||||||
|
render_template( "votre_template.j2",
|
||||||
|
title="Changer de référentiel de compétences",
|
||||||
|
autre_variable=...
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
### Classes css
|
||||||
|
|
||||||
|
`scodoc.css` (et à partir de 9.7, `scodoc97.css`) définissent quelques classes à usage général:
|
||||||
|
|
||||||
|
- `div.scobox`: boite (bords arrondis, fond uni) regroupant des éléments.
|
||||||
|
|
||||||
|
- `div.scobox-title` le titre de la boite
|
||||||
|
- `div.scobox-buttons` boutons en bas de boite.
|
||||||
|
|
||||||
|
- `p.help`, `div.help`: explications, aide.
|
||||||
|
- ...
|
||||||
|
|
||||||
## Accès à la base de donnée
|
## Accès à la base de donnée
|
||||||
|
|
||||||
Sauf exception (requêtes exotiques, problèmes de performance) à discuter, les
|
Sauf exception (requêtes exotiques, problèmes de performance) à discuter, les
|
||||||
accès à la base se font à travers l'ORM *SQLAlchemy*. Mes modèles sont définis
|
accès à la base se font à travers l'ORM *SQLAlchemy*. Les modèles sont définis
|
||||||
dans `app/models`, sauf les comptes utilisateurs qui sont dans
|
dans `app/models`, sauf les comptes utilisateurs qui sont dans
|
||||||
`/app/auth/models.py`.
|
`/app/auth/models.py`.
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user