update documentation

doc/about/introduction.rst

@@ -10,7 +10,7 @@ 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 entretiens é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é 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.
+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 du projet
 ------------------------

doc/about/tech.rst

@@ -15,6 +15,13 @@ L'écosystème Javascript étant à peine naissant et les frameworks allant et v
 
 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é potentiellemet 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
 -------
 
@@ -27,7 +34,7 @@ Le python est un langage de programmation interprété multi paradigme sorti en
 
 .. note::
 
-	Puisque toutes les dépendances du backend sont des packages Python, elles sont toutes ajoutées directement dans le fichier **requirements.txt** à la racine du projet.
+    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
 ~~~~~~
@@ -37,7 +44,10 @@ Django
 
 Django est un framework web pour Python apparu en 2005. Il fourni un grand nombre de fonctionnalités pour développer un site rapidement et simplement. Cela inclu entre autre un serveur Web de développement, un parseur d'URLs pour le routage des différentes URI du site, un ORM (Object-Relational Mapper) pour la gestion de la base de donnée ainsi qu'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 / SQLite
+Il est possible que la version de Django utilisée ne soit pas la plus récente.
+En effet, la version de Django utilisée est systématiquement celle munie d'un support au long-terme.
+
+PostgreSQL / SQLite3
 ~~~~~~~~~~~~~~~~~~~
 
 | `Site officiel PostgreSQL <https://www.postgresql.org/>`__
@@ -48,7 +58,7 @@ Comme la majorité des sites internet, le Sith de l'AE enregistre ses données d
 Le principal à retenir ici est :
 
 * Sur la version de production nous utilisons PostgreSQL, c'est cette version qui doit fonctionner en priorité
-* Sur les versions de développement, pour faciliter l'installation du projet, nous utilisons la technologie SQLite qui ne requiert aucune installation spécifique. 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.
+* 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.
 
 Frontend
 --------
@@ -82,7 +92,39 @@ jQuery
 
 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 fourni 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 libraire reste très agréable à utiliser et économise parfois beaucoup de temps. Ça fonctionne et ça fonctionne très bien. C'est maintenu, léger et pratique, il n'y a pas de raison particulière de s'en séparer.
+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.
+
+VueJS
+~~~~~
+
+`Site officiel <https://vuejs.org/>`__
+
+jQuery permet de facilement manipuler le DOM et faire des requêtes en AJAX,
+mais est moins pratique à utiliser pour créer des applications réactives.
+C'est pour cette raison que Vue a été intégré au projet.
+
+Vue est une librairie Javascript qui se concentre sur le rendu déclaratif et la composition des composants.
+C'est une technologie très utilisée pour la création d'applications web monopages (ce que le site n'est pas)
+mais son architecture progressivement adoptable permet aisément d'adapter son
+comportement à une application multipage comme le site AE.
+
+A ce jour, il est utilisé pour l'interface des barmen, dans l'application des comptoirs.
+
+AlpineJS
+~~~~~~~~
+
+`Site officiel <https://alpinejs.dev/>`__
+
+Dans une démarche similaire à celle de l'introduction de Vue, Alpine a aussi fait son
+apparition au sein des dépendances Javascript du site.
+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 de Vue, mais est beaucoup plus léger, un peu plus facile à prendre en main
+et ne s'embarasse pas d'un DOM virtuel.
+De par son architecture, il 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
 ~~~~
@@ -102,11 +144,11 @@ Fontawesome regroupe tout un ensemble d'icônes libres de droits utilisables fac
 
 .. note::
 
-	C'est une dépendance capricieuse qu'il évolue très vite et qu'il faut très souvent mettre à jour.
+    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.
+    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.
 
 Documentation
 -------------
@@ -140,17 +182,28 @@ Git
 
 `Site officiel <https://git-scm.com/>`__
 
-Git est un logiciel de gestion de versions écrit par Linus Torsvald 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 version 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 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 version 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).
 
-GitLab
+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://about.gitlab.com/>`__
-| `Instance de l'AE <https://github.com/ae-utbm/>`__
+| `Site officiel <https://github.com>`__
+| `Page github d'AE-Dev <https://github.com/ae-utbm/>`__
 
-GitLab est une alternative libre à GitHub. 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.
+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é.
 
-C'est au travers de cette plate-forme que le Sith de l'AE est géré, sur une instance hébergée directement sur nos serveurs.
+Depuis le 1er Octobre 2022, GitHub remplace GitLab dans un soucis de facilité d'entretien,
+les machines sur lesquelles tournent le site étant de plus en plus vielles, il devenait très
+difficile d'effectuer les mise à jours de sécurité du GitLab sans avoir de soucis matériel.
+pour l'hébergement et la gestion des projets informatiques de l'AE.
 
 Sentry
 ~~~~~~
@@ -166,7 +219,9 @@ Poetry
 `Utiliser Poetry <https://python-poetry.org/docs/basic-usage/>`__
 
 Poetry est un utilitaire qui permet de créer et gérer des environements 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èles 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érent sans impacter le système sur lequel le tout est installé.
+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érent sans impacter le système sur lequel le tout est installé.
+
+Les dépendances utilisées par poetry sont déclarées dans le fichier `pyproject.toml`, situé à la racine du projet.
 
 Black
 ~~~~~
@@ -175,4 +230,4 @@ Black
 
 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 black qui est un formateur automatique de code. Une fois l'outil lancé, il parcours la codebase pour y repérer les fautes de norme et les corrige automatiquement sans que l'utilisateur ai à 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.
+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 black qui est un formateur automatique de code. Une fois l'outil lancé, il parcours la codebase pour y repérer les fautes de norme et les corrige automatiquement sans que l'utilisateur n'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.

doc/about/versioning.rst

@@ -3,11 +3,11 @@ Le versioning
 
 Dans le monde du développement, nous faisons face à un problème relativement étrange pour un domaine aussi avancé : on est brouillon.
 
-On teste, on envoie, ça marche pas, on reteste, c'est ok. Par contre, on a oublie plein d'exceptions. Et on refactor. Ça marche mieux mais c'est moins rapide, etc, etc.
+On teste, on envoie, ça marche pas, on reteste, c'est ok. Par contre, on a oublié plein d'exceptions. Et on refactor. Ça marche mieux mais c'est moins rapide, etc.
 
 Et derrière tout ça, on fait des trucs qui marchent puis on se retrouve dans la mouise parce qu'on a effacé un morceau de code qui nous aurait servi plus tard.
 
-Pour palier à ce problème, le programmeur a créé un principe révolutionnaire (ouais... à mon avis, on s'est inspiré d'autres trucs, mais on va dire que c'est nous les créateurs) : le Versioning (*Apparition inexpliquée*).
+Pour pallier ce problème, le programmeur a créé un principe révolutionnaire (ouais... à mon avis, on s'est inspiré d'autres trucs, mais on va dire que c'est nous les créateurs) : le Versioning (*Apparition inexpliquée*).
 
 D'après projet-isika (c'est pas wikipedia ouais, ils étaient pas clairs eux), le versioning (ou versionnage en français mais c'est quand même vachement dégueu comme mot) consiste à travailler directement sur le code source d'un projet, en gardant toutes les versions précédentes. Les outils du versioning aident les développeurs à travailler parallèlement sur différentes parties du projet et à revenir facilement aux étapes précédentes de leur travail en cas de besoin. L’utilisation d’un logiciel de versioning est devenue quasi-indispensable pour tout développeur, même s’il travaille seul.