From 54af894b826a61557d72031b68f916902354a0df Mon Sep 17 00:00:00 2001 From: Sli Date: Tue, 16 Jul 2024 23:35:24 +0200 Subject: [PATCH] Improve documentation --- .github/workflows/deploy.yml | 2 +- .github/workflows/taiste.yml | 2 +- docs/howto/logo.md | 22 ++++++++++++++ docs/howto/querysets.md | 2 +- docs/tutorial/etransaction.md | 2 +- docs/tutorial/perms.md | 56 ++++++++++++++++++----------------- mkdocs.yml | 5 ++-- 7 files changed, 58 insertions(+), 33 deletions(-) create mode 100644 docs/howto/logo.md diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 5338eef7..2ebeca97 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -37,7 +37,7 @@ jobs: pushd ${{secrets.SITH_PATH}} git pull - poetry install --with prod --without dev,docs,tests + poetry install --with prod --without docs,tests poetry run ./manage.py install_xapian poetry run ./manage.py migrate echo "yes" | poetry run ./manage.py collectstatic diff --git a/.github/workflows/taiste.yml b/.github/workflows/taiste.yml index 7da84c43..b83682ec 100644 --- a/.github/workflows/taiste.yml +++ b/.github/workflows/taiste.yml @@ -36,7 +36,7 @@ jobs: pushd ${{secrets.SITH_PATH}} git pull - poetry install --with prod --without dev,docs,tests + poetry install --with prod --without docs,tests poetry run ./manage.py install_xapian poetry run ./manage.py migrate echo "yes" | poetry run ./manage.py collectstatic diff --git a/docs/howto/logo.md b/docs/howto/logo.md new file mode 100644 index 00000000..6db5b289 --- /dev/null +++ b/docs/howto/logo.md @@ -0,0 +1,22 @@ +## Les logos de promo + +Une fois par an, il est généralement nécessaire d'ajouter le +nouveau logo d'une promo. C'est un processus manuel. + +!!!note "Automatisation" + + Créer une interface automatique sur le site serait compliqué + et long à faire. Les erreurs de format des utilisateurs sont + généralement nombreuses et on se retrouverais souvent avec + des logos ratatinés. Il est donc plus simple et plus fiable + de faire cette opération manuellement, ça prend quelques + minutes et on est certain de la qualité à la fin. + +Les logos de promo sont à manuellement ajouter dans le projet. +Ils se situent dans le dossier `core/static/core/img/`. + +Leur format est le suivant: + +* PNG à fond transparent +* Taille 120x120 px +* Nom `promo_xx.png` diff --git a/docs/howto/querysets.md b/docs/howto/querysets.md index 61576686..93f4dbf2 100644 --- a/docs/howto/querysets.md +++ b/docs/howto/querysets.md @@ -27,7 +27,7 @@ Django est dans ce deuxième cas. C'est pourquoi nous ne parlerons pas ici de son fonctionnement exact ni de toutes les fonctions que l'on peut utiliser -(la doc officielle fait déjà ça mieux que nous), +(la [doc officielle](https://docs.djangoproject.com/fr/stable/topics/db/queries/) fait déjà ça mieux que nous), mais plutôt des pièges courants et des astuces pour les éviter. diff --git a/docs/tutorial/etransaction.md b/docs/tutorial/etransaction.md index 44118856..f4c1298b 100644 --- a/docs/tutorial/etransaction.md +++ b/docs/tutorial/etransaction.md @@ -7,5 +7,5 @@ est trop complexe pour être résumée ici. Nous ne pouvons donc que vous redirigez vers la doc du crédit agricole : -https://www.ca-moncommerce.com/espace-client-mon-commerce/up2pay-e-transactions/ma-documentation/ +[https://www.ca-moncommerce.com/espace-client-mon-commerce/up2pay-e-transactions/ma-documentation/](https://www.ca-moncommerce.com/espace-client-mon-commerce/up2pay-e-transactions/ma-documentation/) diff --git a/docs/tutorial/perms.md b/docs/tutorial/perms.md index f8e5ad14..b5f7c2cf 100644 --- a/docs/tutorial/perms.md +++ b/docs/tutorial/perms.md @@ -14,11 +14,11 @@ Il existe trois niveaux de permission : - Voir l'objet Chacune de ces permissions est vérifiée par une méthode -dédiée de la classe `User` : +dédiée de la classe [User][core.models.User] : -- Editer les propriéts : `User.is_owner(obj)` -- Editer les valeurs : `User.can_edit(obj)` -- Voir : `User.can_view(obj)` +- Editer les propriéts : [User.is_owner(obj)][core.models.User.is_owner] +- Editer les valeurs : [User.can_edit(obj)][core.models.User.can_edit] +- Voir : [User.can_view(obj)][core.models.User.can_view] Ces méthodes vont alors résoudre les permissions dans cet ordre : @@ -115,9 +115,9 @@ reposent les vérifications de permission. Elles sont disponibles dans le contexte par défaut du moteur de template et peuvent être utilisées à tout moment. -- `can_edit_prop(obj, user)` : équivalent de `obj.is_owned_by(user)` -- `can_edit(obj, user)` : équivalent de `obj.can_be_edited_by(user)` -- `can_view(obj, user)` : équivalent de `obj.can_be_viewed_by(user)` +- [can_edit_prop(obj, user)][core.views.can_edit_prop] : équivalent de `obj.is_owned_by(user)` +- [can_edit(obj, user)][core.views.can_edit] : équivalent de `obj.can_be_edited_by(user)` +- [can_view(obj, user)][core.views.can_view] : équivalent de `obj.can_be_viewed_by(user)` Voici un exemple d'utilisation dans un template : @@ -170,29 +170,31 @@ class ArticlesCreateView(CanCreateMixin, CreateView): Les mixins suivants sont implémentés : -- `CanCreateMixin` : l'utilisateur peut-il créer l'objet ? -- `CanEditPropMixin` : l'utilisateur peut-il éditer les propriétés de l'objet ? -- `CanEditMixin` : L'utilisateur peut-il éditer l'objet ? -- `CanViewMixin` : L'utilisateur peut-il voir l'objet ? -- `UserIsRootMixin` : L'utilisateur a-t-il les droit root ? -- `FormerSubscriberMixin` : L'utilisateur a-t-il déjà été cotisant ? -- `UserIsLoggedMixin` : L'utilisateur est-il connecté ? +- [CanCreateMixin][core.views.CanCreateMixin] : l'utilisateur peut-il créer l'objet ? +- [CanEditPropMixin][core.views.CanEditPropMixin] : l'utilisateur peut-il éditer les propriétés de l'objet ? +- [CanEditMixin][core.views.CanEditMixin] : L'utilisateur peut-il éditer l'objet ? +- [CanViewMixin][core.views.CanViewMixin] : L'utilisateur peut-il voir l'objet ? +- [UserIsRootMixin][core.views.UserIsRootMixin] : L'utilisateur a-t-il les droit root ? +- [FormerSubscriberMixin][core.views.FormerSubscriberMixin] : L'utilisateur a-t-il déjà été cotisant ? +- [UserIsLoggedMixin][core.views.UserIsLoggedMixin] : L'utilisateur est-il connecté ? (à éviter ; préférez `LoginRequiredMixin`, fourni par Django) !!!danger "Performance" - Ce système maison de permissions ne rend pas trop mal, d'un point de vue esthétique. - Mais d'un point de vue performance, c'est un désastre. - Vérifier une seule permission peut demander plusieurs requêtes à la db. - Et chaque vérification recommence dès le début. - Il n'y a aucune jointure en db. - Le mieux qu'on a trouvé comme pansement sur ça, c'est utiliser le cache, - mais c'est seulement un pansement, qui ne rattrape pas les erreurs architecturales. + Ce système maison de permissions ne rend pas trop mal, d'un point de vue esthétique. + Mais d'un point de vue performance, il est souvent plus que problématique. + En effet, toutes les permissions sont dynamiquement calculées et + nécessitent plusieurs appels en base de données qui ne se résument pas à + une « simple » jointure mais à plusieurs requêtes différentes et + difficiles à optimiser. De plus, à chaque calcul de permission, il est + nécessaire de recommencer tous les calculs depuis le début. + La solution à ça est de mettre du cache de session sur les tests effectués + récemment, mais cela engendre son autre lot de problèmes. - Sur une vue où on manipule un seul objet, passe encore. - Mais sur les `ListView`, on peut arriver à des temps - de réponse extrêmement élevés. - - Faites donc doublement, triplement, quadruplement attention, - quand vous manipulez le système de permissions. + Sur une vue où on manipule un seul objet, passe encore. + Mais sur les `ListView`, on peut arriver à des temps + de réponse extrêmement élevés. + + Faites donc doublement, triplement, quadruplement attention, + quand vous manipulez le système de permissions. diff --git a/mkdocs.yml b/mkdocs.yml index 7b53fead..d09c5c57 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -63,14 +63,15 @@ nav: - Gestion des groupes: tutorial/groups.md - Etransactions: tutorial/etransaction.md - How-to: - - Terminal: howto/terminal.md - - Direnv: howto/direnv.md - L'ORM de Django: howto/querysets.md - Gérer les migrations: howto/migrations.md - Gérer les traductions: howto/translation.md - Configurer pour la production: howto/prod.md + - Ajouter un logo de promo: howto/logo.md - Ajouter une cotisation: howto/subscriptions.md - Modifier le weekmail: howto/weekmail.md + - Terminal: howto/terminal.md + - Direnv: howto/direnv.md - Reference: - accounting: - reference/accounting/models.md