fix doc display

core/auth/api_permissions.py

@@ -3,7 +3,8 @@
 Some permissions are global (like `IsInGroup` or `IsRoot`),
 and some others are per-object (like `CanView` or `CanEdit`).
 
-Examples:
+Example:
+    ```python
     # restrict all the routes of this controller
     # to subscribed users
     @api_controller("/foo", permissions=[IsSubscriber])
@@ -33,6 +34,7 @@ Examples:
         ]
         def bar_delete(self, bar_id: int):
             # ...
+    ```
 """
 
 from typing import Any

core/auth/mixins.py

@@ -21,6 +21,7 @@
 # Place - Suite 330, Boston, MA 02111-1307, USA.
 #
 #
+from __future__ import annotations
 
 import types
 import warnings
@@ -30,11 +31,11 @@ from django.contrib.auth.mixins import AccessMixin, PermissionRequiredMixin
 from django.core.exceptions import ImproperlyConfigured, PermissionDenied
 from django.views.generic.base import View
 
-from core.models import User
-
 if TYPE_CHECKING:
     from django.db.models import Model
 
+    from core.models import User
+
 
 def can_edit_prop(obj: Any, user: User) -> bool:
     """Can the user edit the properties of the object.
@@ -46,7 +47,7 @@ def can_edit_prop(obj: Any, user: User) -> bool:
     Returns:
         True if user is authorized to edit object properties else False
 
-    Examples:
+    Example:
         ```python
         if not can_edit_prop(self.object ,request.user):
             raise PermissionDenied
@@ -65,7 +66,7 @@ def can_edit(obj: Any, user: User) -> bool:
     Returns:
         True if user is authorized to edit object else False
 
-    Examples:
+    Example:
         ```python
         if not can_edit(self.object, request.user):
             raise PermissionDenied
@@ -86,7 +87,7 @@ def can_view(obj: Any, user: User) -> bool:
     Returns:
         True if user is authorized to see object else False
 
-    Examples:
+    Example:
         ```python
         if not can_view(self.object ,request.user):
             raise PermissionDenied

docs/reference/core/api_permissions.md

@@ -1 +0,0 @@
-::: core.auth.api_permissions

docs/reference/core/auth.md

@@ -0,0 +1,32 @@
+## Backend
+
+::: core.auth.backends
+    handler: python
+    options:
+        heading_level: 3
+        members:
+            - SithModelBackend
+
+## Mixins
+
+::: core.auth.mixins
+    handler: python
+    options:
+        heading_level: 3
+        members:
+            - can_edit_prop
+            - can_edit
+            - can_view
+            - CanCreateMixin
+            - CanEditMixin
+            - CanViewMixin
+            - FormerSubscriberMixin
+            - PermissionOrAuthorRequiredMixin
+
+
+## API Permissions
+
+::: core.auth.api_permissions
+    handler: python
+    options:
+        heading_level: 3

docs/tutorial/perms.md

@@ -412,9 +412,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)][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)`
+- [can_edit_prop(obj, user)][core.auth.mixins.can_edit_prop] : équivalent de `obj.is_owned_by(user)`
+- [can_edit(obj, user)][core.auth.mixins.can_edit] : équivalent de `obj.can_be_edited_by(user)`
+- [can_view(obj, user)][core.auth.mixins.can_view] : équivalent de `obj.can_be_viewed_by(user)`
 
 Voici un exemple d'utilisation dans un template :
 
@@ -483,23 +483,24 @@ Les mixins suivants sont implémentés :
     de création et crée l'objet sans le persister en base de données, puis
     vérifie les droits sur cet objet non-persisté.
     Le danger de ce système vient de multiples raisons :
-      - Les vérifications se faisant sur un objet non persisté,
-        l'utilisation de mécanismes nécessitant une persistance préalable
-        peut mener à des comportements indésirés, voire à des erreurs.
-      - Les développeurs de django ayant tendance à restreindre progressivement
-        les actions qui peuvent être faites sur des objets non-persistés,
-        les mises-à-jour de django deviennent plus compliquées.
-      - La vérification des droits ne se fait que dans les requêtes POST,
-        à la toute fin de la requête.
-        Tout ce qui arrive avant n'est absolument pas protégé.
-        Toute opération (même les suppressions et les créations) qui ont
-        lieu avant la persistance de l'objet seront appliquées,
-        même sans permission.
-      - Si un développeur du site fait l'erreur de surcharger
-        la méthode `form_valid` (ce qui est plutôt courant,
-        lorsqu'on veut accomplir certaines actions 
-        quand un formulaire est valide), on peut se retrouver
-        dans une situation où l'objet est persisté sans aucune protection.
+
+    - Les vérifications se faisant sur un objet non persisté,
+      l'utilisation de mécanismes nécessitant une persistance préalable
+      peut mener à des comportements indésirés, voire à des erreurs.
+    - Les développeurs de django ayant tendance à restreindre progressivement
+      les actions qui peuvent être faites sur des objets non-persistés,
+      les mises-à-jour de django deviennent plus compliquées.
+    - La vérification des droits ne se fait que dans les requêtes POST,
+      à la toute fin de la requête.
+      Tout ce qui arrive avant n'est absolument pas protégé.
+      Toute opération (même les suppressions et les créations) qui ont
+      lieu avant la persistance de l'objet seront appliquées,
+      même sans permission.
+    - Si un développeur du site fait l'erreur de surcharger
+      la méthode `form_valid` (ce qui est plutôt courant,
+      lorsqu'on veut accomplir certaines actions 
+      quand un formulaire est valide), on peut se retrouver
+      dans une situation où l'objet est persisté sans aucune protection.
 
 !!!danger "Performance"
 

mkdocs.yml

@@ -98,7 +98,7 @@ nav:
       - Champs de modèle: reference/core/model_fields.md
       - reference/core/views.md
       - reference/core/schemas.md
-      - reference/core/api_permissions.md
+      - reference/core/auth.md
     - counter:
       - reference/counter/models.md
       - reference/counter/views.md