Improve documentation

.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

.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

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`

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.
 

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

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.
 

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