mirror of
https://github.com/ae-utbm/sith.git
synced 2025-07-10 20:09:25 +00:00
Rewrite documentation with MkDocs
This commit is contained in:
thomas girod
303
docs/explanation/conventions.md
Normal file
303
docs/explanation/conventions.md
Normal file
@ -0,0 +1,303 @@
|
||||
Cette page traite des conventions utilisées dans le développement du site.
|
||||
|
||||
## Langue
|
||||
|
||||
Les noms, de fonctions, de classe, de fichiers et de dossiers sont en anglais.
|
||||
De même, les commentaires et les docstrings sont rédigés en anglais.
|
||||
|
||||
En revanche la documentation est rédigée en français.
|
||||
En effet, les développeurs et les développeuses
|
||||
qui ont été, sont et seront amenés à travailler
|
||||
sur le site sont presque tous des francophones.
|
||||
Or, la bonne compréhension prime.
|
||||
Une documentation, qui se doit d'utiliser au mieux
|
||||
les mots justes, compris de manière juste,
|
||||
gagne à être écrite en langue vernaculaire,
|
||||
lorsqu'on est assuré qu'une coopération
|
||||
internationale est peu probable.
|
||||
|
||||
De la sorte, on s'assure au mieux que les
|
||||
rédacteurs et rédactrices s'expriment bien
|
||||
et que, réciproquement, les lecteurs et lectrices
|
||||
comprennent au mieux.
|
||||
|
||||
A ce titre, on ne vous en voudra pas
|
||||
si vous rédigez des commentaires ou des docstrings
|
||||
en français.
|
||||
|
||||
En revanche, le code en lui-même doit
|
||||
rester impérativement en anglais ;
|
||||
les instructions étant en langue anglaise,
|
||||
introduire des mots français au milieu crée un
|
||||
contraste qui nuit à la compréhension.
|
||||
|
||||
De manière générale, demandez-vous juste à qui vous êtes en train d'écrire :
|
||||
|
||||
- si vous écrivez pour la machine, c'est en anglais
|
||||
- si vous écrivez pour des êtres humains, c'est en français
|
||||
|
||||
## Gestion de version
|
||||
|
||||
Le projet utilise Git pour gérer les versions et
|
||||
GitHub pour héberger le dépôt distant.
|
||||
|
||||
L'arbre possède deux branches protégées : `master` et `taiste`.
|
||||
|
||||
`master` est la branche contenant le code tel qu'il
|
||||
tourne effectivement sur le vrai site de l'AE.
|
||||
Celle-ci doit, autant que faire se peut, rester impeccable.
|
||||
|
||||
`taiste` est la branche de référence pour le développement.
|
||||
Cette dernière est régulièrement déployée sur le
|
||||
site de test.
|
||||
Elle permet de s'assurer que les diverses modifications
|
||||
fonctionnent bien entre elles et fonctionnent bien
|
||||
sur le serveur, avant d'être envoyées sur master.
|
||||
|
||||
### Gestion des branches
|
||||
|
||||
Toutes les modifications appliquées sur `taiste`
|
||||
doivent se faire via des Pull Requests
|
||||
depuis les différentes branches de développement.
|
||||
Toutes les modifications appliquées sur `master`
|
||||
doivent se faire via des Pull Requests
|
||||
depuis `taiste`, ou bien depuis une branche
|
||||
de *hotfix*, dans le cas où il faut réparer
|
||||
un bug urgent apparu de manière impromptue.
|
||||
|
||||
Aucun `push` direct n'est admis, ni sur l'une,
|
||||
ni sur l'autre branche.
|
||||
|
||||
En obligeant à passer par des PR,
|
||||
on s'assure qu'au moins une autre personne
|
||||
aura lu votre code et que les outils de test
|
||||
et de vérification de code auront validé vos modifications.
|
||||
|
||||
Par extension du mode de travail par PR,
|
||||
les branches `master` et `taiste` ne peuvent
|
||||
recevoir du code que sous la forme de merge commits.
|
||||
|
||||
De plus, ces branches doivent recevoir, mais jamais donner
|
||||
(à part entre elles).
|
||||
Lorsqu'une modification a été effectuée sur `taiste`
|
||||
et que vous souhaitez la récupérer dans une de vos
|
||||
branches, vous devez procéder par `rebase`,
|
||||
et non par `merge`.
|
||||
|
||||
En d'autres termes, vous devez respecter les deux règles suivantes :
|
||||
|
||||
1. Les branches `master` et `taiste` ne doivent contenir que des merge commits
|
||||
2. Seules les branches `master` et `taiste` peuvent contenir des merge commits
|
||||
|
||||
=== "Bien ✔️"
|
||||
|
||||
```mermaid
|
||||
gitGraph:
|
||||
commit id: "initial commit"
|
||||
branch bar
|
||||
checkout main
|
||||
checkout bar
|
||||
commit id: "baz"
|
||||
checkout main
|
||||
merge bar id: "Merge branch bar"
|
||||
branch foo
|
||||
commit id: "foo a"
|
||||
commit id: "foo b"
|
||||
commit id: "foo c"
|
||||
checkout main
|
||||
merge foo id: "Merge branch foo"
|
||||
```
|
||||
|
||||
=== "Pas bien ❌"
|
||||
|
||||
```mermaid
|
||||
gitGraph:
|
||||
commit
|
||||
branch bar
|
||||
branch foo
|
||||
commit id: "foo a"
|
||||
commit id: "foo b"
|
||||
checkout main
|
||||
checkout bar
|
||||
commit id: "baz"
|
||||
checkout main
|
||||
merge bar id: "Merge branch bar"
|
||||
checkout foo
|
||||
merge main id: "Merge branch main"
|
||||
commit id: "foo c"
|
||||
checkout main
|
||||
merge foo id: "Merge branch foo"
|
||||
```
|
||||
|
||||
## Style de code
|
||||
|
||||
### Conventions de nommage
|
||||
|
||||
Les conventions de nommage sont celles de la
|
||||
[PEP8](https://peps.python.org/pep-0008/) :
|
||||
|
||||
- les classes sont en PascalCase (ex: `class SacredGraal`)
|
||||
- les constantes sont en MACRO_CASE (ex: `FAVOURITE_COLOUR = "blue"`)
|
||||
- les fonctions et les variables sont en snake_case (ex: `swallow_origin = "african"`)
|
||||
- les fichiers et dossiers contenant du code sont en snake_case
|
||||
- les fichiers et les dossiers contenant de la documentation sont en kebab-case
|
||||
|
||||
En parallèle de la casse, les règles
|
||||
de formatage du code sont celles du formateur Ruff.
|
||||
Ces règles sont automatiquement appliquées quand
|
||||
vous faites tourner Ruff, donc vous n'avez pas à trop
|
||||
vous poser de questions de ce côté-là.
|
||||
|
||||
En ce qui concerne les autres langages utilisés
|
||||
(Jinja, SCSS, Javascript), nous n'avons pas fixé
|
||||
de convention à suivre.
|
||||
Pour SCSS et Javascript, vous pouvez utiliser
|
||||
Prettier, avec sa configuration par défaut,
|
||||
qui est plutôt bonne.
|
||||
|
||||
### Qualité du code
|
||||
|
||||
Pour s'assurer de la qualité du code, Ruff est également utilisé.
|
||||
|
||||
Tout comme pour le format, Ruff doit tourner avant chaque commit.
|
||||
|
||||
!!!note "to edit or not to edit"
|
||||
|
||||
Vous constaterez sans doute que `ruff format` modifie votre code,
|
||||
mais que `ruff check` vous signale juste une liste
|
||||
d'erreurs sans rien modifier.
|
||||
|
||||
En effet, `ruff format` ne s'occupe que de la forme du code,
|
||||
alors que `ruff check` regarde la logique du code.
|
||||
Si Ruff modifiait automatiquement la logique du code,
|
||||
ça serait un coup à introduire plus de bugs que ça n'en résoud.
|
||||
|
||||
Il existe cependant certaines catégories d'erreurs que Ruff
|
||||
peut réparer de manière sûre.
|
||||
Pour appliquer ces réparations, faites :
|
||||
|
||||
```bash
|
||||
ruff check --fix
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
La documentation est écrite en markdown, avec les fonctionnalités
|
||||
offertes par MkDocs, MkDocs-material et leurs extensions.
|
||||
|
||||
La documentation est intégralement en français, à l'exception
|
||||
des exemples, qui suivent les conventions données plus haut.
|
||||
|
||||
### Découpage
|
||||
|
||||
La séparation entre les différentes parties de la documentation se fait
|
||||
en suivant la méthodologie [Diataxis](https://diataxis.fr/).
|
||||
On compte quatre sections :
|
||||
|
||||
1. Explications : parlez dans cette section de ce qui est bon à savoir
|
||||
sans que ça touche aux détails précis de l'implémentation.
|
||||
Si vous parlez de *pourquoi* un choix a été fait ou que vous montrez
|
||||
grossièrement les contours d'une partie du projet, c'est une explication.
|
||||
2. Tutoriels : parlez dans cette section d'étapes précises
|
||||
ou de détails d'implémentation qu'un nouveau développeur
|
||||
doit suivre pour commencer à travailler sur le projet.
|
||||
3. Utilisation : parlez dans cette section de méthodes utiles
|
||||
pour un développeur qui a déjà pris en main le projet.
|
||||
Voyez cette partie comme un livre de recettes de cuisine.
|
||||
4. Référence : parlez dans cette section des détails d'implémentation du projet.
|
||||
En réalité, vous n'aurez pas besoin de beaucoup vous pencher dessus,
|
||||
puisque cette partie est composée presque uniquement
|
||||
des docstrings présents dans le code.
|
||||
|
||||
Pour plus de détails, lisez directement la documentation de Diataxis,
|
||||
qui expose ces concepts de manière beaucoup plus complète.
|
||||
|
||||
### Style
|
||||
|
||||
Votre markdown doit être composé de lignes courtes ;
|
||||
à partir de 88 caractères, c'est trop long.
|
||||
Si une phrase est trop longue pour tenir sur une ligne,
|
||||
vous pouvez l'écrire sur plusieurs.
|
||||
|
||||
Une ligne ne peut pas contenir plus d'une seule phrase.
|
||||
Dit autrement, quand vous finissez une phrase,
|
||||
faites systématiquement un saut de ligne.
|
||||
|
||||
=== "Bien ✔️"
|
||||
|
||||
```markdown linenums="1"
|
||||
First shalt thou take out the Holy Pin,
|
||||
then shalt thou count to three, no more, no less.
|
||||
Three shalt be the number thou shalt count,
|
||||
and the number of the counting shalt be three.
|
||||
Four shalt thou not count, neither count thou two,
|
||||
excepting that thou then proceed to three.
|
||||
Five is right out.
|
||||
Once the number three, being the third number, be reached,
|
||||
then lobbest thou thy Holy Hand Grenade of Antioch towards thou foe,
|
||||
who being naughty in My sight, shall snuff it.
|
||||
```
|
||||
|
||||
=== "Pas bien ❌"
|
||||
|
||||
```markdown linenums="1"
|
||||
First shalt thou take out the Holy Pin, then shalt thou count to three, no more, no less. Three shalt be the number thou shalt count, and the number of the counting shalt be three. Four shalt thou not count, neither count thou two, excepting that thou then proceed to three. Five is right out. Once the number three, being the third number, be reached, then lobbest thou thy Holy Hand Grenade of Antioch towards thou foe, who being naughty in My sight, shall snuff it.
|
||||
```
|
||||
|
||||
À noter que ces deux exemples donnent le même résultat
|
||||
dans la documentation générée.
|
||||
Mais la version avec de courtes lignes est beaucoup
|
||||
plus facile à modifier et à versioner.
|
||||
|
||||
!!!warning "Grammaire et orthographe"
|
||||
|
||||
Ca peut paraitre évident dit comme ça, mais c'est toujours bon à rappeler :
|
||||
évitez de faire des fautes de français.
|
||||
Relisez vous quand vous avez fini d'écrire.
|
||||
|
||||
|
||||
### Docstrings
|
||||
|
||||
Les docstrings sont écrits en suivant la norme
|
||||
[Google](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html)
|
||||
et les fonctionnalités de [Griffe](https://mkdocstrings.github.io/griffe/docstrings/).
|
||||
|
||||
Ils doivent être explicites sur ce que la fonction accomplit,
|
||||
mais ne pas parler de comment elle le fait.
|
||||
Un bon docstring est celui qui dit exactement
|
||||
ce qu'il faut pour qu'on puisse savoir comment
|
||||
utiliser la fonction ou la classe documentée sans avoir à lire son code.
|
||||
|
||||
Tout comme les pédales d'une voiture :
|
||||
pour pouvoir conduire, vous avez juste besoin
|
||||
de savoir ce qui se passe quand vous appuyez dessus.
|
||||
La connaissance de la mécanique interne est inutile dans ce cadre.
|
||||
|
||||
N'hésitez pas à mettre des examples dans vos docstrings.
|
||||
|
||||
## Pourquoi une partie du projet ne respecte pas ces conventions ?
|
||||
|
||||
Parce que le projet est vieux.
|
||||
Le commit initial date du 18 novembre 2015.
|
||||
C'était il y a presque dix ans au moment
|
||||
où ces lignes sont écrites.
|
||||
Au début, on ne se posait pas forcément
|
||||
ce genre de questions.
|
||||
Puis le projet a grandi, de manière sédimentaire,
|
||||
fonctionnalité après fonctionnalité,
|
||||
développé par des personnes n'ayant pas toutes la
|
||||
même esthétique.
|
||||
|
||||
On retrouve dans le code ces inspirations diverses
|
||||
de personnes variées à travers une décennie.
|
||||
Au bout d'un moment, il est bon de se poser
|
||||
et de normaliser les choses.
|
||||
|
||||
De ce côté-là, une première pierre a été posée
|
||||
en novembre 2018, avec l'utilisation d'un formateur.
|
||||
Il convient de poursuivre ce travail d'unification.
|
||||
|
||||
Cependant, là où on peut reformater automatiquement
|
||||
du code, il faut y aller à la main pour retravailler
|
||||
un style de code.
|
||||
C'est un travail de fourmi qui prendra du temps.
|
||||
101
docs/explanation/index.md
Normal file
101
docs/explanation/index.md
Normal file
@ -0,0 +1,101 @@
|
||||
## Objectifs
|
||||
|
||||
Le but de ce projet est de fournir à
|
||||
l'Association des Étudiants de l'UTBM
|
||||
une plate-forme pratique et centralisée de ses services.
|
||||
Le Sith de l'AE tient à jour le registre des cotisations
|
||||
à l'association, prend en charge la trésorerie,
|
||||
les ventes de produits et services,
|
||||
la diffusion d’événements,
|
||||
la gestion de la laverie et bien plus encore.
|
||||
|
||||
C'est un projet bénévole qui tire ses origines des années 2000.
|
||||
Il s'agit de la troisième version du site de l'AE.
|
||||
Son développement a commencé en 2015.
|
||||
C'est une réécriture complète en rupture totale
|
||||
des deux versions qui l'ont précédée.
|
||||
|
||||
## Pourquoi réécrire le site
|
||||
|
||||
L'ancienne version du site, sobrement baptisée
|
||||
[ae2](https://github.com/ae-utbm/sith2),
|
||||
présentait un nombre impressionnant de fonctionnalités.
|
||||
Il avait été écrit en PHP et se basait
|
||||
sur son propre framework maison.
|
||||
|
||||
Malheureusement, son entretien était plus ou
|
||||
moins hasardeux et son framework reposait
|
||||
sur des principes assez différents de ce qui se fait
|
||||
aujourd'hui, rendant la maintenance difficile.
|
||||
De plus, la version de PHP qu'il utilisait
|
||||
était plus que dépréciée et à l'heure de l'arrivée de PHP 7
|
||||
et de sa non-rétrocompatibilité il était vital de faire
|
||||
quelque chose.
|
||||
Il a donc été décidé de le réécrire.
|
||||
|
||||
## La philosophie initiale
|
||||
|
||||
Pour éviter les erreurs du passé,
|
||||
ce projet met l'accent sur la maintenabilité.
|
||||
Le choix des technologies ne s'est donc pas
|
||||
fait uniquement sur le fait qu'elle soit récentes,
|
||||
mais également sur leur robustesse,
|
||||
leur fiabilité et leur potentiel à être maintenu
|
||||
loin dans le futur.
|
||||
|
||||
La maintenabilité passe également par le
|
||||
choix minutieux des dépendances qui doivent,
|
||||
elles aussi, passer l'épreuve du temps
|
||||
pour éviter qu'elles ne mettent le projet en danger.
|
||||
|
||||
Cela passe également par la minimisation
|
||||
des frameworks employés de manière à réduire un maximum
|
||||
les connaissances nécessaires pour contribuer
|
||||
au projet et donc simplifier la prise en main.
|
||||
La simplicité est à privilégier si elle est possible.
|
||||
|
||||
Le projet doit être simple à installer et à déployer.
|
||||
|
||||
Le projet étant à destination d'étudiants,
|
||||
il est préférable de minimiser les ressources
|
||||
utilisées par l'utilisateur final.
|
||||
Il faut qu'il soit au maximum économe en bande
|
||||
passante et calcul côté client.
|
||||
|
||||
Le projet est un logiciel libre et est sous licence GPL.
|
||||
Aucune dépendance propriétaire n'est acceptée.
|
||||
|
||||
## La philosophie, 10 ans plus tard
|
||||
|
||||
Malgré la bonne volonté et le travail colossal
|
||||
fourni par les developpeurs de la version actuelle
|
||||
du projet, force est de constater que nombre d'erreurs
|
||||
ont malheureusement été commises :
|
||||
usage complexe et excessif de certains mécanismes OO,
|
||||
réécriture maison de fonctionnalités de Django,
|
||||
système de gestion des permissions rigide et coûteux
|
||||
en requête à la base de données...
|
||||
|
||||
Mais malgré tout ça, le site tourne.
|
||||
En effet, force est de constater que le pari initial
|
||||
de choisir un framework stable et durable a payé.
|
||||
Aujourd'hui encore, Django est activement maintenu,
|
||||
ses mises à jour sont régulières sans pour autant
|
||||
nécessiter beaucoup de changements lors des changements
|
||||
de version majeure.
|
||||
|
||||
Quant aux erreurs qui ont été commises,
|
||||
que celui qui n'a jamais reconsidéré a posteriori
|
||||
que ce qui lui semblait une bonne architecture
|
||||
était en fait un ensemble brinquebalant,
|
||||
leur jette la première pierre.
|
||||
|
||||
La solidité des fondations ayant été prouvée
|
||||
par l'épreuve du temps,
|
||||
le travail restant à accomplir n'est
|
||||
pas de réécrire encore une fois le site
|
||||
en utilisant encore d'autres technologies,
|
||||
mais plutôt de raboter les surcouches du site,
|
||||
pour refixer le plus solidement possiblement
|
||||
le projet sur ces fondations.
|
||||
|
||||
355
docs/explanation/technos.md
Normal file
355
docs/explanation/technos.md
Normal file
@ -0,0 +1,355 @@
|
||||
Bien choisir ses technologies est crucial
|
||||
puisqu'une fois que le projet est suffisamment avancé,
|
||||
il est très difficile voir impossible de revenir en arrière.
|
||||
|
||||
En novembre 2015, plusieurs choix se présentaient :
|
||||
|
||||
- Continuer avec du PHP
|
||||
- S'orienter vers un langage web
|
||||
plus moderne et à la mode comme le Python ou le Ruby
|
||||
- Baser le site sur un framework Javascript
|
||||
|
||||
Le PHP 5, bientôt 7, de l'époque
|
||||
étant assez discutable comme
|
||||
[cet article le montre](https://eev.ee/blog/2012/04/09/php-a-fractal-of-bad-design/),
|
||||
et l'ancien site ayant laissé un goût amer
|
||||
à certains développeurs, celui-ci a été mis de côté.
|
||||
|
||||
L'écosystème Javascript étant à peine naissant
|
||||
et les frameworks allant et venant en seulement quelques mois,
|
||||
il était impossible de prédire avec certitude
|
||||
si ceux-ci passeraient l'épreuve du temps,
|
||||
il était inconcevable de tout parier là-dessus.
|
||||
|
||||
Ne restait plus que le Python et le Ruby
|
||||
avec les frameworks Django et Ruby On Rails.
|
||||
Ruby ayant une réputation d'être très "cutting edge",
|
||||
c'est Python, un langage bien implanté
|
||||
et ayant fait ses preuves, qui a été retenu.
|
||||
|
||||
Il est à noter que réécrire le site avec un framework PHP
|
||||
comme Laravel ou Symphony eut aussi été possible,
|
||||
ces deux technologies étant assez matures et robustes
|
||||
au moment où le développement a commencé.
|
||||
Cependant, il aurait été potentiellement
|
||||
fastidieux de maintenir en parallèle deux
|
||||
versions de PHP sur le serveur durant toute
|
||||
la durée du développement.
|
||||
Il faut aussi prendre en compte que nous étions
|
||||
à ce moment dégoûtés du PHP.
|
||||
|
||||
## Backend
|
||||
|
||||
### Python 3
|
||||
|
||||
[Site officiel](https://www.python.org/)
|
||||
|
||||
Le python est un langage de programmation
|
||||
interprété multi paradigme sorti en 1991.
|
||||
Il est très populaire dans de nombreux domaines
|
||||
pour sa simplicité d'utilisation,
|
||||
sa polyvalence, sa sécurité ainsi
|
||||
que sa grande communauté de développeur.
|
||||
Sa version 3, non rétro compatible avec sa version 2,
|
||||
a été publiée en 2008.
|
||||
|
||||
!!!note
|
||||
|
||||
Puisque toutes les dépendances du backend sont
|
||||
des packages Python,
|
||||
elles sont toutes ajoutées directement
|
||||
dans le fichier **pyproject.toml**,
|
||||
à la racine du projet.
|
||||
|
||||
### Django
|
||||
|
||||
[Site officiel](https://www.djangoproject.com/)
|
||||
|
||||
[Documentation](https://docs.djangoproject.com/en/latest/)
|
||||
|
||||
Django est un framework web pour Python apparu en 2005.
|
||||
Il fournit un grand nombre de fonctionnalités
|
||||
pour développer un site rapidement et simplement.
|
||||
Cela inclut entre autre un serveur Web de développement,
|
||||
un parseur d'URLs pour le routage,
|
||||
un ORM (Object-Relational Mapper)
|
||||
pour la gestion de la base de donnée,
|
||||
un cadre pour l'écriture et l'exécution des tests,
|
||||
de nombreux utilitaires pour l'internationalisation,
|
||||
les zones horaires et autres,
|
||||
une interface web d'administration aisément configurable,
|
||||
un moteur de templates pour le rendu HTML...
|
||||
|
||||
Django propose une version LTS (Long Term Support)
|
||||
qui reste stable et est maintenu sur des cycles plus longs.
|
||||
Ce sont ces versions qui sont utilisées.
|
||||
|
||||
|
||||
### PostgreSQL / SQLite3
|
||||
|
||||
[Site officiel PostgreSQL](https://www.postgresql.org/)
|
||||
|
||||
[Site officiel SQLite](https://www.sqlite.org/index.html>)
|
||||
|
||||
Comme la majorité des sites internet,
|
||||
le Sith de l'AE enregistre ses données
|
||||
dans une base de données.
|
||||
Nous utilisons une base de donnée relationnelle
|
||||
puisque c'est la manière typique d'utiliser
|
||||
Django et c'est ce qu'utilise son ORM.
|
||||
|
||||
Le principal à retenir ici est :
|
||||
|
||||
- Sur la version de production, nous utilisons PostgreSQL,
|
||||
c'est cette version qui doit fonctionner en priorité.
|
||||
C'est un système de gestion de base de données fiable,
|
||||
puissant, activement maintenu, et particulièrement
|
||||
bien supporté par Django.
|
||||
- Sur les versions de développement,
|
||||
pour faciliter l'installation du projet,
|
||||
nous utilisons la technologie SQLite3
|
||||
qui ne requiert aucune installation spécifique
|
||||
(la librairie `sqlite` est incluse dans les
|
||||
librairies par défaut de Python).
|
||||
Certaines instructions ne sont pas supportées
|
||||
par cette technologie et il est parfois nécessaire
|
||||
d'installer PostgreSQL pour le développement
|
||||
de certaines parties du site
|
||||
(cependant, ces parties sont rares, et vous pourriez
|
||||
même ne jamais en rencontrer une).
|
||||
|
||||
PostgreSQL est-ce avec quoi le site doit fonctionner.
|
||||
Cependant, pour permettre aux développeurs
|
||||
de travailler en installant le moins de dépendances
|
||||
possible sur leur ordinateur,
|
||||
il est également désirable de chercher la compatibilité
|
||||
avec SQLite.
|
||||
Aussi, dans la mesure du possible, nous
|
||||
cherchons à ce que les interactions avec la base
|
||||
de données fonctionnent avec l'un comme avec l'autre.
|
||||
|
||||
Heureusement, et grâce à l'ORM de Django, cette
|
||||
double compatibilité est presque toujours possible.
|
||||
|
||||
## Frontend
|
||||
|
||||
### Jinja2
|
||||
|
||||
[Site officiel](https://jinja.palletsprojects.com/en/latest/)
|
||||
|
||||
Jinja2 est un moteur de template écrit en Python
|
||||
qui s'inspire fortement de la syntaxe des templates de Django.
|
||||
Ce moteur apporte toutefois son lot d'améliorations non négligeables.
|
||||
Il permet par exemple l'ajout de macros,
|
||||
sortes de fonctions écrivant du HTML.
|
||||
|
||||
Un moteur de templates permet de générer
|
||||
du contenu textuel de manière procédural
|
||||
en fonction des données à afficher,
|
||||
cela permet de pouvoir inclure du code proche du Python
|
||||
dans la syntaxe au milieu d'un document
|
||||
contenant principalement du HTML.
|
||||
On peut facilement faire des boucles ou des conditions
|
||||
ainsi même que de l'héritage de templates.
|
||||
|
||||
!!!note
|
||||
le rendu est fait côté serveur,
|
||||
si on souhaite faire des modifications côté client,
|
||||
il faut utiliser du Javascript, rien ne change à ce niveau-là.
|
||||
|
||||
### jQuery
|
||||
|
||||
[Site officiel](https://jquery.com/)
|
||||
|
||||
jQuery est une bibliothèque JavaScript
|
||||
libre et multiplateforme créée pour faciliter
|
||||
l'écriture de scripts côté client
|
||||
dans le code HTML des pages web.
|
||||
La première version est lancée en janvier 2006 par John Resig.
|
||||
|
||||
C'est une vieille technologie et certains
|
||||
feront remarquer à juste titre que le Javascript
|
||||
moderne permet d'utiliser assez simplement
|
||||
la majorité de ce que fournit jQuery
|
||||
sans rien avoir à installer.
|
||||
Cependant, de nombreuses dépendances du projet
|
||||
utilisent encore jQuery qui est toujours
|
||||
très implanté aujourd'hui.
|
||||
Le sucre syntaxique qu'offre cette librairie
|
||||
reste très agréable à utiliser et économise
|
||||
parfois beaucoup de temps.
|
||||
Ça fonctionne et ça fonctionne très bien.
|
||||
C'est maintenu et pratique.
|
||||
|
||||
|
||||
### AlpineJS
|
||||
|
||||
[Site officiel](https://alpinejs.dev/)
|
||||
|
||||
AlpineJS est une librairie légère et minimaliste
|
||||
permettant le rendu dynamique d'éléments sur une page
|
||||
web, code de manière déclarative.
|
||||
La librairie est décrite par ses créateurs comme :
|
||||
"un outil robuste et minimal pour composer un comportement directement dans vos balises".
|
||||
|
||||
Alpine permet d'accomplir la plupart du temps le même résultat qu'un usage des fonctionnalités
|
||||
de base des plus gros frameworks Javascript,
|
||||
mais est beaucoup plus léger, un peu plus facile à prendre en main
|
||||
et ne s'embarrasse pas d'un DOM virtuel.
|
||||
Grâce à son architecture, il est extrêmement
|
||||
bien adapté pour un usage dans un site multipage.
|
||||
C'est une technologie simple et puissante qui se veut comme le jQuery du web moderne.
|
||||
|
||||
### Sass
|
||||
|
||||
[Site officiel](https://sass-lang.com/)
|
||||
|
||||
Sass (Syntactically Awesome Stylesheets) est un langage dynamique
|
||||
de génération de feuilles CSS apparu en 2006.
|
||||
C'est un langage de CSS "amélioré" qui permet
|
||||
l'ajout de variables
|
||||
(à une époque où le CSS ne les supportait pas),
|
||||
de fonctions, mixins ainsi qu'une syntaxe pour
|
||||
imbriquer plus facilement et proprement les règles
|
||||
sur certains éléments.
|
||||
Le Sass est traduit en CSS directement côté serveur
|
||||
et le client ne reçoit que du CSS.
|
||||
|
||||
C'est une technologie stable,
|
||||
mature et pratique qui ne nécessite pas énormément
|
||||
d'apprentissage.
|
||||
|
||||
### Fontawesome
|
||||
|
||||
[Site officiel](https://fontawesome.com>)
|
||||
|
||||
Fontawesome regroupe tout un ensemble
|
||||
d'icônes libres de droits utilisables facilement
|
||||
sur n'importe quelle page web.
|
||||
Ils sont simples à modifier puisque modifiables
|
||||
via le CSS et présentent l'avantage de fonctionner
|
||||
sur tous les navigateurs contrairement
|
||||
à un simple icône unicode qui s'affiche
|
||||
lui différemment selon la plate-forme.
|
||||
|
||||
!!!note
|
||||
|
||||
C'est une dépendance capricieuse qui évolue très vite
|
||||
et qu'il faut très souvent mettre à jour.
|
||||
|
||||
!!!warning
|
||||
|
||||
Il a été décidé de **ne pas utiliser**
|
||||
de CDN puisque le site ralentissait régulièrement.
|
||||
Il est préférable de fournir cette dépendance avec le site.
|
||||
|
||||
## Workflow
|
||||
|
||||
### Git
|
||||
|
||||
[Site officiel](https://git-scm.com/)
|
||||
|
||||
Git est un logiciel de gestion de versions écrit par
|
||||
Linus Torvalds pour les besoins du noyau linux en 2005.
|
||||
C'est ce logiciel qui remplace svn anciennement
|
||||
utilisé pour gérer les sources du projet
|
||||
(rappelez vous, l'ancien site date d'avant 2005).
|
||||
Git est plus complexe à utiliser,
|
||||
mais est bien plus puissant,
|
||||
permet de gérer plusieurs versions en parallèle
|
||||
et génère des codebases vraiment plus légères puisque
|
||||
seules les modifications sont enregistrées
|
||||
(contrairement à svn qui garde une copie
|
||||
de la codebase par version).
|
||||
|
||||
Git s'étant imposé comme le principal outil de gestion de versions,
|
||||
sa communauté est très grande et sa documentation très fournie.
|
||||
Il est également aisé de trouver des outils avec une interface graphique,
|
||||
qui simplifient grandement son usage.
|
||||
|
||||
### GitHub
|
||||
|
||||
[Site officiel](https://github.com)
|
||||
|
||||
[Page github du Pôle Informatique de l'AE](https://github.com/ae-utbm/)
|
||||
|
||||
Github est un service web d'hébergement et de gestion de développement de logiciel.
|
||||
C'est une plate-forme avec interface web permettant de déposer du code géré avec Git
|
||||
offrant également de l'intégration continue et du déploiement automatique.
|
||||
C'est au travers de cette plate-forme que le Sith de l'AE est géré.
|
||||
|
||||
### Sentry
|
||||
|
||||
[Site officiel](https://sentry.io)
|
||||
|
||||
[Instance de l'AE](https://ae2.utbm.fr)
|
||||
|
||||
Sentry est une plate-forme libre qui permet
|
||||
de se tenir informé des bugs qui ont lieu sur le site.
|
||||
À chaque crash du logiciel (erreur 500),
|
||||
une erreur est envoyée sur la plate-forme
|
||||
et il est indiqué précisément à quelle ligne de code
|
||||
celle-ci a eu lieu, à quelle heure, combien de fois,
|
||||
avec quel navigateur la page a été visitée et même éventuellement
|
||||
un commentaire de l'utilisateur qui a rencontré le bug.
|
||||
|
||||
C'est un outil incroyablement pratique
|
||||
pour savoir tout ce qui ne fonctionne pas,
|
||||
et surtout pour récolter toutes les informations
|
||||
nécessaires à la réparation des bugs.
|
||||
|
||||
### Poetry
|
||||
|
||||
[Utiliser Poetry](https://python-poetry.org/docs/basic-usage/)
|
||||
|
||||
Poetry est un utilitaire qui permet de créer et gérer
|
||||
des environnements Python de manière simple et intuitive.
|
||||
Il permet également de gérer et mettre à jour
|
||||
le fichier de dépendances.
|
||||
|
||||
L'avantage d'utiliser poetry
|
||||
(et les environnements virtuels en général)
|
||||
est de pouvoir gérer plusieurs projets différents
|
||||
en parallèle puisqu'il permet d'avoir sur sa
|
||||
machine plusieurs environnements différents et
|
||||
donc plusieurs versions d'une même dépendance
|
||||
dans plusieurs projets différents sans impacter
|
||||
le système sur lequel le tout est installé.
|
||||
|
||||
Poetry possède également l'avantage par rapport à un simple venv
|
||||
que les versions exactes de toutes les dépendances,
|
||||
y compris celles utilisées par d'autres dépendances,
|
||||
sont consignées dans un fichier `.lock`.
|
||||
On est donc sûr et certain que deux environnements virtuels
|
||||
configurés avec le même fichier lock utiliseront
|
||||
exactement les mêmes versions des mêmes dépendances,
|
||||
y compris si celles-ci ne sont pas indiquées explicitement.
|
||||
|
||||
Les dépendances utilisées par poetry sont déclarées
|
||||
dans le fichier `pyproject.toml`,
|
||||
situé à la racine du projet.
|
||||
|
||||
### Ruff
|
||||
|
||||
[Site officiel](https://astral.sh/ruff)
|
||||
|
||||
Pour faciliter la lecture du code,
|
||||
il est toujours appréciable d'avoir
|
||||
une norme d'écriture cohérente.
|
||||
C'est généralement à l'étape de relecture
|
||||
des modifications par les autres contributeurs
|
||||
que sont repérées ces fautes de normes
|
||||
qui se doivent d'être corrigées pour le bien commun.
|
||||
|
||||
Imposer une norme est très fastidieux,
|
||||
que ce soit pour ceux qui relisent
|
||||
ou pour ceux qui écrivent.
|
||||
C'est pour cela que nous utilisons Ruff,
|
||||
qui est un formateur et linter automatique de code.
|
||||
Une fois l'outil lancé, il parcourt la codebase
|
||||
pour y repérer les fautes de norme et les erreurs de logique courantes
|
||||
et les corrige automatiquement (quand c'est possible)
|
||||
sans que l'utilisateur ait à s'en soucier.
|
||||
Bien installé, il peut effectuer ce travail
|
||||
à chaque sauvegarde d'un fichier dans son éditeur,
|
||||
ce qui est très agréable pour travailler.
|
||||
Reference in New Issue
Block a user