From da2c15525445d6b7960726e3a41c1575a5edfc50 Mon Sep 17 00:00:00 2001 From: Thomas Girod Date: Sun, 18 Dec 2022 15:27:33 +0100 Subject: [PATCH 1/2] update documentation --- doc/about/introduction.rst | 2 +- doc/about/tech.rst | 83 +++++++++++++--- doc/about/versioning.rst | 4 +- doc/frequent/subscriptions.rst | 2 +- doc/start/devtools.rst | 62 +++++++----- doc/start/hello_world.rst | 52 +++++----- doc/start/install.rst | 135 +++++++++++++++----------- doc/start/structure.rst | 170 +++++++++++++++++---------------- pyproject.toml | 2 - 9 files changed, 307 insertions(+), 205 deletions(-) diff --git a/doc/about/introduction.rst b/doc/about/introduction.rst index 42760743..3d682ead 100644 --- a/doc/about/introduction.rst +++ b/doc/about/introduction.rst @@ -10,7 +10,7 @@ Pourquoi réécrire le site L'ancienne version du site, sobrement baptisée `ae2 `_ 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 ------------------------ diff --git a/doc/about/tech.rst b/doc/about/tech.rst index 43ac1de3..9585655b 100644 --- a/doc/about/tech.rst +++ b/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 `__ @@ -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 `__ + +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 `__ + +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 `__ -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 `__ -| `Instance de l'AE `__ +| `Site officiel `__ +| `Page github d'AE-Dev `__ -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 `__ 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. \ No newline at end of file +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. \ No newline at end of file diff --git a/doc/about/versioning.rst b/doc/about/versioning.rst index ab713746..8d32e39a 100644 --- a/doc/about/versioning.rst +++ b/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. diff --git a/doc/frequent/subscriptions.rst b/doc/frequent/subscriptions.rst index c151b35a..fc446201 100644 --- a/doc/frequent/subscriptions.rst +++ b/doc/frequent/subscriptions.rst @@ -8,7 +8,7 @@ Il arrive régulièrement que le type de cotisation proposé varie en prix et en Comprendre la configuration --------------------------- -Pour modifier les cotisations disponnibles, tout se gère dans la configuration avec la variable *SITH_SUBSCRIPTIONS*. Dans cet exemple, nous allons ajouter une nouvelle cotisation d'un mois. +Pour modifier les cotisations disponibles, tout se gère dans la configuration avec la variable *SITH_SUBSCRIPTIONS*. Dans cet exemple, nous allons ajouter une nouvelle cotisation d'un mois. .. code-block:: python diff --git a/doc/start/devtools.rst b/doc/start/devtools.rst index 3688d099..9256bfb4 100644 --- a/doc/start/devtools.rst +++ b/doc/start/devtools.rst @@ -3,35 +3,53 @@ Configurer son environnement de développement Le projet n'est en aucun cas lié à un quelconque environnement de développement. Il est possible pour chacun de travailler avec les outils dont il a envie et d'utiliser l'éditeur de code avec lequel il est le plus à l'aise. -Pour donner une idée, Skia a écrit une énorme partie de projet avec l'éditeur *vim* sur du GNU/Linux alors que Sli a utilisé *Sublime Text* sur MacOS. +Pour donner une idée, Skia a écrit une énorme partie de projet avec l'éditeur *Vim* sur du GNU/Linux +alors que Sli a utilisé *Sublime Text* sur MacOS et que Maréchal travaille avec PyCharm +sur Windows muni de WSL. Configurer Black pour son éditeur --------------------------------- -Tous les détails concernant l'installation de black sont ici : https://black.readthedocs.io/en/stable/editor_integration.html +.. note:: -Néanmoins, nous tenterons de vous faire ici un résumé pour deux éditeurs de textes populaires que sont VsCode et Sublime Text. + Black est inclus dans les dépendances du projet. + Si vous avez réussi à terminer l'installation, vous n'avez donc pas de configuration + supplémentaire à effectuer. -.. sourcecode:: bash +Pour utiliser Black, placez-vous à la racine du projet et lancez la commande suivante : - # Installation de black - pip install black +.. code-block:: + + black . + +Black va alors faire son travail sur l'ensemble du projet puis vous dire quels documents +ont été reformatés. + +Appeler Black en ligne de commandes avant de pousser votre code sur Github +est une technique qui marche très bien. +Cependant, vous risquez de souvent l'oublier. +Or, lorsque le code est mal formaté, la pipeline bloque les PR sur les branches protégées. + +Pour éviter de vous faire régulièrement blacked, vous pouvez configurer +votre éditeur pour que Black fasse son travail automatiquement à chaque édition d'un fichier. +Nous tenterons de vous faire ici un résumé pour deux éditeurs de textes populaires +que sont VsCode et Sublime Text. VsCode ~~~~~~ .. warning:: - Il faut installer black dans son environement virtuel pour cet éditeur + Il faut installer black dans son environement virtuel pour cet éditeur Black est directement pris en charge par l'extension pour le Python de VsCode, il suffit de rentrer la configuration suivante : .. sourcecode:: json - { - "python.formatting.provider": "black", - "editor.formatOnSave": true - } + { + "python.formatting.provider": "black", + "editor.formatOnSave": true + } Sublime Text ~~~~~~~~~~~~ @@ -42,19 +60,19 @@ Il suffit ensuite d'ajouter dans les settings du projet (ou directement dans les .. sourcecode:: json - { - "sublack.black_on_save": true - } + { + "sublack.black_on_save": true + } Si vous utilisez le plugin `anaconda `__, pensez à modifier les paramètres du linter pep8 pour éviter de recevoir des warnings dans le formatage de black comme ceci : .. sourcecode:: json - { - "pep8_ignore": [ - "E203", - "E266", - "E501", - "W503" - ] - } + { + "pep8_ignore": [ + "E203", + "E266", + "E501", + "W503" + ] + } diff --git a/doc/start/hello_world.rst b/doc/start/hello_world.rst index 9d3c2b2a..88e585bf 100644 --- a/doc/start/hello_world.rst +++ b/doc/start/hello_world.rst @@ -32,13 +32,13 @@ Enfin, on vas inclure les URLs de cette application dans le projet sous le préf # sith/urls.py urlpatterns = [ ... - url(r"^hello/", include("hello.urls", namespace="hello", app_name="hello")), + path("hello/", include("hello.urls", namespace="hello", app_name="hello")), ] Un Hello World simple --------------------- -Dans un premier temps, nous allons créer une vue qui vas charger un template en utilisant le système de vues basées sur les classes de Django. +Dans un premier temps, nous allons créer une vue qui va charger un template en utilisant le système de vues basé sur les classes de Django. .. code-block:: python @@ -63,26 +63,26 @@ On vas ensuite créer le template. {# On remplis la partie titre du template étendu #} {# Il s'agit du titre qui sera affiché dans l'onglet du navigateur #} {% block title %} - Hello World - {% endblock title %} + Hello World + {% endblock %} {# On remplis le contenu de la page #} {% block content %} -

Hello World !

- {% endblock content %} +

Hello World !

+ {% endblock %} Enfin, on crée l'URL. On veut pouvoir appeler la page depuis https://localhost:8000/hello, le préfixe indiqué précédemment suffit donc. .. code-block:: python # hello/urls.py - from django.conf.urls import url + from django.urls import path from hello.views import HelloView urlpatterns = [ # Le préfixe étant retiré lors du passage du routeur d'URL # dans le fichier d'URL racine du projet, l'URL à matcher ici est donc vide - url(r"^$", HelloView.as_view(), name="hello"), + path("", HelloView.as_view(), name="hello"), ] Et voilà, c'est fini, il ne reste plus qu'à lancer le serveur et à se rendre sur la page. @@ -95,13 +95,12 @@ Dans cette partie, on cherche à détecter les numéros passés dans l'URL pour .. code-block:: python # hello/urls.py - from django.conf.urls import url + from django.urls import path from hello.views import HelloView urlpatterns = [ - url(r"^$", HelloView.as_view(), name="hello"), - # On utilise un regex pour matcher un numéro - url(r"^(?P[0-9]+)$", HelloView.as_view(), name="hello"), + path("", HelloView.as_view(), name="hello"), + path("", HelloView.as_view(), name="hello"), ] Cette deuxième URL vas donc appeler la classe crée tout à l'heure en lui passant une variable *hello_id* dans ses *kwargs*, nous allons la récupérer et la passer dans le contexte du template en allant modifier la vue. @@ -143,16 +142,16 @@ Enfin, on modifie le template en rajoutant une petite condition sur la présence {% extends "core/base.jinja" %} {% block title %} - Hello World + Hello World {% endblock title %} {% block content %} -

- Hello World ! - {% if hello_id -%} - {{ hello_id }} - {%- endif -%} -

+

+ Hello World ! + {% if hello_id -%} + {{ hello_id }} + {%- endif -%} +

{% endblock content %} .. note:: @@ -162,7 +161,7 @@ Enfin, on modifie le template en rajoutant une petite condition sur la présence À l'assaut des modèles ---------------------- -Pour cette dernière partie, nous allons ajouter une entrée dans la base de donnée et l'afficher dans un template. Nous allons ainsi créer un modèle nommé *Article* qui contiendra une entrée de texte pour le titre et une autre pour le contenu. +Pour cette dernière partie, nous allons ajouter une entrée dans la base de données et l'afficher dans un template. Nous allons ainsi créer un modèle nommé *Article* qui contiendra une entrée de texte pour le titre et une autre pour le contenu. Commençons par le modèle en lui même. @@ -203,7 +202,7 @@ On n'oublie pas l'URL. urlpatterns = [ ... - url(r"^articles$", ArticlesListView.as_view(), name="articles_list") + path("articles/", ArticlesListView.as_view(), name="articles_list") ] Et enfin le template. @@ -227,7 +226,7 @@ Et enfin le template. Maintenant que toute la logique de récupération et d'affichage est terminée, la page est accessible à l'adresse https://localhost:8000/hello/articles. -Mais, j'ai une erreur ! Il se passe quoi ?! Et bien c'est simple, nous avons crée le modèle mais il n'existe pas dans la base de données. Il est dans un premier temps important de créer un fichier de migrations qui contiens des instructions pour la génération de celle-ci. Ce sont les fichiers qui sont enregistrés dans le dossier migration. Pour les générer à partir des classes de modèles qu'on viens de manipuler il suffit d'une seule commande. +Mais, j'ai une erreur ! Il se passe quoi ?! Et bien c'est simple, nous avons créé le modèle mais il n'existe pas dans la base de données. Il est dans un premier temps important de créer un fichier de migrations qui contient des instructions pour la génération de celles-ci. Ce sont les fichiers qui sont enregistrés dans le dossier migration. Pour les générer à partir des classes de modèles qu'on vient de manipuler il suffit d'une seule commande. .. code-block:: bash @@ -245,7 +244,7 @@ J'ai toujours une erreur ! Mais oui, c'est pas fini, faut pas aller trop vite. M ./manage.py migrate -Et voilà, là il n'y a plus d'erreur. Tout fonctionne et on a une superbe page vide puisque aucun contenu pour cette table n'est dans la base. Nous allons en rajouter. Pour cela nous allons utiliser le fichier *core/management/commands/populate.py* qui contiens la commande qui initialise les données de la base de données de test. C'est un fichier très important qu'on viendra à modifier assez souvent. Nous allons y ajouter quelques articles. +Et voilà, là il n'y a plus d'erreur. Tout fonctionne et on a une superbe page vide puisque aucun contenu pour cette table n'est dans la base. Nous allons en rajouter. Pour cela nous allons utiliser le fichier *core/management/commands/populate.py* qui contient la commande qui initialise les données de la base de données de test. C'est un fichier très important qu'on viendra à modifier assez souvent. Nous allons y ajouter quelques articles. .. code-block:: python @@ -262,14 +261,15 @@ Et voilà, là il n'y a plus d'erreur. Tout fonctionne et on a une superbe page ... + # les deux syntaxes ci-dessous sont correctes et donnent le même résultat Article(title="First hello", content="Bonjour tout le monde").save() - Article(title="Tutorial", content="C'était un super tutoriel").save() + Article.objects.create(title="Tutorial", content="C'était un super tutoriel") -On regénère enfin les données de test en lançant la commande que l'on viens de modifier. +On regénère enfin les données de test en lançant la commande que l'on vient de modifier. .. code-block:: bash ./manage.py setup -On reviens sur https://localhost:8000/hello/articles et cette fois-ci nos deux articles apparaissent correctement. \ No newline at end of file +On revient sur https://localhost:8000/hello/articles et cette fois-ci nos deux articles apparaissent correctement. \ No newline at end of file diff --git a/doc/start/install.rst b/doc/start/install.rst index 2aa51991..f94e9122 100644 --- a/doc/start/install.rst +++ b/doc/start/install.rst @@ -7,7 +7,6 @@ Dépendances du système Certaines dépendances sont nécessaires niveau système : * poetry -* libmysqlclient * libssl * libjpeg * libxapian-dev @@ -15,18 +14,80 @@ Certaines dépendances sont nécessaires niveau système : * python * gettext * graphviz -* mysql-client (pour migrer de l'ancien site) + +Sur Windows +~~~~~~~~~~~ + +Chers utilisateurs de Windows, quel que soit votre amour de Windows, +de Bill Gates et des bloatwares, je suis désolé +de vous annoncer que, certaines dépendances étant uniquement disponibles sur des sytèmes UNIX, +il n'est pas possible développer le site sur Windows. + +Heureusement, il existe une alternative qui ne requiert pas de désinstaller votre +OS ni de mettre un dual boot sur votre ordinateur : :code:`WSL`. + +- **Prérequis:** vous devez être sur Windows 10 version 2004 ou ultérieure (build 19041 & versions ultérieures) ou Windows 11. +- **Plus d'info:** `docs.microsoft.com `_ + +.. sourcecode:: bash + + # dans un shell Windows + wsl --install + + # afficher la liste des distribution disponible avec WSL + wsl -l -o + + # installer WSL avec une distro (ubuntu conseillé) + wsl --install -d + +.. note:: + + Si vous rencontrez le code d'erreur ``0x80370102``, regardez les réponses de ce `post `_. + +Une fois :code:`WSL` installé, mettez à jour votre distro & installez les dépendances **(voir la partie installation sous Ubuntu)**. + +.. note:: + + Comme `git` ne fonctionne pas de la même manière entre Windows & Unix, il est nécessaire de cloner le repository depuis Windows. + (cf: `stackoverflow.com `_) + +Pour accéder au contenu d'un répertoire externe à :code:`WSL`, il suffit simplement d'utiliser la commande suivante: + +.. sourcecode:: bash + + # oui c'est beau, simple et efficace + cd /mnt//vos/fichiers/comme/dhab + +Une fois l'installation des dépendances terminée (juste en dessous), il vous suffira, pour commencer à dev, d'ouvrir votre plus bel IDE et d'avoir 2 consoles: +1 console :code:`WSL` pour lancer le projet & 1 console pour utiliser :code:`git` + +.. note:: + + A ce stade, si vous avez réussi votre installation de :code:`WSL` ou bien qu'il + était déjà installé, vous pouvez effectuer la mise en place du projet en suivant + les instructions pour Ubuntu. + Sur Ubuntu ~~~~~~~~~~ .. sourcecode:: bash - sudo apt install libssl-dev libjpeg-dev zlib1g-dev python-dev libffi-dev python-dev libgraphviz-dev pkg-config libxapian-dev gettext git + # Sait-on jamais + sudo apt update + + sudo apt install python-is-python3 # Permet d'utiliser python au lieu de python3, c'est optionel + + sudo apt install build-essentials libssl-dev libjpeg-dev zlib1g-dev python-dev \ + libffi-dev python-dev-is-python3 libgraphviz-dev pkg-config libxapian-dev \ + gettext git + curl -sSL https://install.python-poetry.org | python - - # To include mysql for importing old bdd - sudo apt install libmysqlclient-dev +.. note:: + + Si vous avez réussi à exécuter les instructions ci-dessus sans trop de problèmes, + vous pouvez passer à la partie :ref:`Finalise installation` Sur MacOS ~~~~~~~~~ @@ -51,61 +112,21 @@ Pour installer les dépendances, il est fortement recommandé d'installer le ges Si vous rencontrez des erreurs lors de votre configuration, n'hésitez pas à vérifier l'état de votre installation homebrew avec :code:`brew doctor` -Sur Windows avec :code:`WSL` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - .. note:: - Comme certaines dépendances sont uniquement disponible dans un environnement Unix, il est obligatoire de passer par :code:`WSL` pour installer le projet. + Si vous avez réussi à exécuter les instructions ci-dessus sans trop de problèmes, + vous pouvez passer à la partie :ref:`Finalise installation` -- **Prérequis:** vous devez exécuter Windows 10 versions 2004 et ultérieures (build 19041 & versions ultérieures) ou Windows 11. -- **Plus d'info:** `docs.microsoft.com `_ - -.. sourcecode:: bash +.. _Finalise installation: - # dans un shell Windows - wsl --install - - # afficher la liste des distribution disponible avec WSL - wsl -l -o - - # installer WSL avec une distro - wsl --install -d - -.. note:: - - Si vous rencontrez le code d'erreur ``0x80370102``, regardez les réponses de ce `post `_. - -Une fois :code:`WSL` installé, mettez à jour votre distro & installez les dépendances **(voir la partie installation sous Ubuntu)**. - -.. note:: - - Comme `git` ne fonctionne pas de la même manière entre Windows & Unix, il est nécessaire de cloner le repository depuis Windows. - (cf: `stackoverflow.com `_) - -Pour accéder au contenu d'un répertoire externe à :code:`WSL`, il suffit simplement d'utiliser la commande suivante: +Finaliser l'installation +------------------------ .. sourcecode:: bash - - # oui c'est beau, simple et efficace - cd /mnt//vos/fichiers/comme/dhab - -.. note:: - - Une fois l'installation des dépendances terminée (juste en dessous), il vous suffira, pour commencer à dev, d'ouvrir votre plus bel IDE et d'avoir 2 consoles: - 1 console :code:`WSL` pour lancer le projet & 1 console pour utiliser :code:`git` - -Installer le projet ------------------------------------ - -.. sourcecode:: bash - - # Sait-on jamais - sudo apt update # Les commandes git doivent se faire depuis le terminal de Windows si on utilise WSL ! git clone https://github.com/ae-utbm/sith3.git - cd Sith + cd sith3 # Création de l'environnement et installation des dépendances poetry install @@ -113,7 +134,7 @@ Installer le projet # Activation de l'environnement virtuel poetry shell - # Prépare la base de donnée + # Prépare la base de données python manage.py setup # Installe les traductions @@ -144,15 +165,21 @@ Il faut toujours avoir préalablement activé l'environnement virtuel comme fait .. note:: - Le serveur est alors accessible à l'adresse http://localhost:8000. + Le serveur est alors accessible à l'adresse http://localhost:8000 ou bien http://127.0.0.1:8000/. Générer la documentation ------------------------ -La documentation est automatiquement mise en ligne sur readthedocs à chaque envoi de code sur GitLab. +La documentation est automatiquement mise en ligne sur readthedocs à chaque envoi de code sur Github. Pour l'utiliser en local ou globalement pour la modifier, il existe une commande du site qui génère la documentation et lance un serveur la rendant accessible à l'adresse http://localhost:8080. Cette commande génère la documentation à chacune de ses modifications, inutile de relancer le serveur à chaque fois. +.. note:: + + Les dépendances pour la documentation sont optionnelles. + Avant de commencer à travailler sur la doc, il faut donc les installer + avec la commande :code:`poetry install -E docs` + .. sourcecode:: bash python manage.py documentation diff --git a/doc/start/structure.rst b/doc/start/structure.rst index 5bbfde32..1c5e3cb5 100644 --- a/doc/start/structure.rst +++ b/doc/start/structure.rst @@ -28,75 +28,76 @@ Le découpage en applications ---------------------------- | /projet -| **sith/** -| Application principale du projet. -| **accounting/** -| Ajoute un système de comptabilité. -| **api/** -| Application où mettre les endpoints publiques d'API. -| **club/** -| Contiens les modèles liés aux clubs associatifs et ajoute leur gestion. -| **com/** -| Fournis des outils de communications aux clubs (weekmail, affiches…). -| **core/** -| Application la plus importante. Contiens les principales surcouches -| liées au projet comme la gestion des droits et les templates de base. -| **counter/** -| Ajoute des comptoirs de vente pour les clubs et gère les ventes sur les lieux de vie. -| **data/** -| Contiens les fichiers statiques ajoutées par les utilisateurs. -| N'est pas suivit par Git. -| **doc/** -| Contiens la documentation du projet. -| **eboutic/** -| Ajoute le comptoir de vente en ligne. Permet d'acheter en carte bancaire. -| **election/** -| Ajoute un système d'élection permettant d'élire les représentants étudiants. -| **forum/** -| Ajoute un forum de discutions. -| **launderette/** -| Permet la gestion des laveries. -| **locale/** -| Contiens les fichiers de traduction. -| **matmat/** -| Système de recherche de membres. -| **pedagogy/** -| Contiens le guide des UVs. -| **rootplace/** -| Ajoute des outils destinés aux administrateurs. -| **static/** -| Contiens l'ensemble des fichiers statiques ajoutés par les développeurs. -| Ce dossier est généré par le framework, il est surtout utile en production. -| Ce dossier n'es pas suivit par Git. -| **stock/** -| Système de gestion des stocks. -| **subscription/** -| Ajoute la gestion des cotisations des membres. -| **trombi/** -| Permet la génération du trombinoscope des élèves en fin de cursus. -| **.coveragec** -| Configure l'outil permettant de calculer la couverture des tests sur le projet. -| **.gitignore** -| Permet de définir quels fichiers sont suivis ou non par Git. -| **.gitlab-ci.yml** -| Permet de configurer la pipeline automatique de GitLab. -| **.readthedocs.yml** -| Permet de configurer la génération de documentation sur Readthedocs. -| **.db.sqlite3** -| Base de données de développement par défaut. Est automatiquement généré -| lors de la configuration du projet en local. N'est pas suivis par Git. -| **LICENSE** -| Licence du projet. -| **LICENSE.old** -| Ancienne licence du projet. -| **manage.py** -| Permet de lancer les commandes liées au framework Django. -| **migrate.py** -| Contiens des scripts de migration à exécuter pour importer les données de l'ancien site. -| **README.rst** -| Fichier de README. À lire pour avoir des informations sur le projet. -| **requirements.txt** -| Contiens les dépendances Python du projet. +| **sith/** +| Application principale du projet. +| **accounting/** +| Ajoute un système de comptabilité. +| **api/** +| Application où mettre les endpoints publiques d'API. +| **club/** +| Contient les modèles liés aux clubs et assos et ajoute leur gestion. +| **com/** +| Fournis des outils de communications aux clubs (weekmail, affiches…). +| **core/** +| Application la plus importante. Contient les principales surcouches +| liées au projet comme la gestion des droits et les templates de base. +| **counter/** +| Ajoute des comptoirs de vente pour les clubs et gère les ventes sur les lieux de vie. +| **data/** +| Contient les fichiers statiques ajoutés par les utilisateurs. +| N'est pas suivi par Git. +| **doc/** +| Contient la documentation du projet. +| **eboutic/** +| Ajoute le comptoir de vente en ligne. Permet d'acheter en carte bancaire. +| **election/** +| Ajoute un système d'élection permettant d'élire les représentants étudiants. +| **forum/** +| Ajoute un forum de discussion. +| **launderette/** +| Permet la gestion des laveries. +| **locale/** +| Contient les fichiers de traduction. +| **matmat/** +| Système de recherche de membres. +| **pedagogy/** +| Contient le guide des UVs. +| **rootplace/** +| Ajoute des outils destinés aux administrateurs. +| **static/** +| Contient l'ensemble des fichiers statiques ajoutés par les développeurs. +| Ce dossier est généré par le framework, il est surtout utile en production ; +| évitez d'y toucher pendant le développement. +| Ce dossier n'est pas suivi par Git. +| **stock/** +| Système de gestion des stocks. +| **subscription/** +| Ajoute la gestion des cotisations des membres. +| **trombi/** +| Permet la génération du trombinoscope des élèves en fin de cursus. +| **.coveragec** +| Configure l'outil permettant de calculer la couverture des tests sur le projet. +| **.gitignore** +| Permet de définir quels fichiers sont suivis ou non par Git. +| **.github/** +| Contient les fichiers de configuration des actions github. +| **.readthedocs.yml** +| Permet de configurer la génération de documentation sur Readthedocs. +| **.db.sqlite3** +| Base de données de développement par défaut. Est automatiquement généré +| lors de la configuration du projet en local. N'est pas suivie par Git. +| **LICENSE** +| Licence du projet. +| **LICENSE.old** +| Ancienne licence du projet. +| **manage.py** +| Permet de lancer les commandes liées au framework Django. +| **migrate.py** +| Contiens des scripts de migration à exécuter pour importer les données de l'ancien site. +| **README.md** +| Fichier de README. À lire pour avoir des informations sur le projet. +| **pyproject.toml** +| Contient les dépendances Python du projet. L'application principale @@ -107,16 +108,20 @@ L'application principale | Permet de définir le dossier comme un package Python. | Ce fichier est vide. | **settings.py** -| Contiens les paramètres par défaut du projet. +| Contient les paramètres par défaut du projet. | Ce fichier est versionné et fait partie intégrant de celui-ci. -| **settings_curtom.py** -| Contiens les paramètres spécifiques à l'installation courante. -| Ce fichier n'est pas versionné et surcharges les paramètres par défaut. +| Notez que les informations sensibles qui se trouvent dans ce fichier +| ne sont pas celles utilisées en production. +| Ce sont des paramètres factices préremplies pour faciliter la mise en place +| du projet qui sont surchargés en production par les vrais paramètres. +| **settings_custom.py** +| Contient les paramètres spécifiques à l'installation courante. +| Ce fichier n'est pas versionné et surcharge les paramètres par défaut. | **urls.py** -| Contiens les routes d'URLs racines du projet. -| On y inclus les autres fichiers d'URLs et leur namespace. +| Contient les routes d'URLs racines du projet. +| On y inclut les autres fichiers d'URLs et leur namespace. | **toolbar_debug.py** -| Contiens la configuration de la barre de debug à gauche à destination +| Contient la configuration de la barre de debug à gauche à destination | du site de développement. | **et_keys/** | Contiens la clef publique du système de paiement E-Transactions. @@ -131,23 +136,22 @@ Le contenu d'une application | /app1 | **__init__.py** | Permet de définir le dossier comme un package Python. -| Ce fichier est généralement vide. | **models.py** | C'est là que les modèles sont définis. Ces classes définissent -| les tables dans la base de donnée. +| les tables dans la base de données. | **views.py** | C'est là où les vues sont définies. | **admin.py** | C'est là que l'on déclare quels modèles doivent apparaître | dans l'interface du module d'administration de Django. | **tests.py** -| Ce fichier contiens les tests fonctionnels, unitaires -| mais aussi d'intégrations qui sont lancés par la pipeline. +| Ce fichier contient les tests fonctionnels, unitaires +| et d'intégrations qui sont lancés par la pipeline. | **urls.py** -| On y défini les URLs de l'application et on les lies aux vues. +| On y définit les URLs de l'application et on les lie aux vues. | **migrations/** | Ce dossier sert à stocker les fichiers de migration de la base -| de données générées par la commande *makemigrations*. +| de données générés par la commande *makemigrations*. | **templates/** -| Ce dossier ci contiens généralement des sous dossiers et sert +| Ce dossier-ci contient généralement des sous-dossiers et sert | à accueillir les templates. Les sous dossiers servent de namespace. diff --git a/pyproject.toml b/pyproject.toml index 99b3958f..4206ccfd 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -47,7 +47,6 @@ django-countries = "^7.4.2" dict2xml = "^1.7.2" # Extra optional dependencies -mysqlclient = { version = "^2.0.3", optional = true } coverage = {version = "^5.5", optional = true} # Docs extra dependencies @@ -57,7 +56,6 @@ sphinx-copybutton = {version = "^0.4.0", optional = true} [tool.poetry.extras] testing = ["coverage"] -migration = ["mysqlclient"] docs = ["Sphinx", "sphinx-rtd-theme", "sphinx-copybutton"] [tool.poetry.dev-dependencies] From 754be1c9c9fd1bb48fbe170f318b51238537f970 Mon Sep 17 00:00:00 2001 From: thomas girod <56346771+imperosol@users.noreply.github.com> Date: Tue, 20 Dec 2022 21:17:52 +0100 Subject: [PATCH 2/2] Update doc/about/tech.rst Co-authored-by: Julien Constant <49886317+Juknum@users.noreply.github.com> --- doc/about/tech.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/about/tech.rst b/doc/about/tech.rst index 9585655b..475d7b38 100644 --- a/doc/about/tech.rst +++ b/doc/about/tech.rst @@ -202,7 +202,7 @@ C'est au travers de cette plate-forme que le Sith de l'AE est géré. 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. +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