Improve documentation

This commit is contained in:
Antoine Bartuccio 2024-07-16 23:35:24 +02:00 committed by thomas girod
parent e1ac75f394
commit 54af894b82
7 changed files with 58 additions and 33 deletions

View File

@ -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

View File

@ -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

22
docs/howto/logo.md Normal file
View File

@ -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`

View File

@ -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.

View File

@ -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/)

View File

@ -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.

View File

@ -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