Add/ Complete docstring for every models.

apps/activity/models.py

@@ -9,7 +9,12 @@ from django.utils.translation import gettext_lazy as _
 
 class ActivityType(models.Model):
     """
-    Type of Activity, (e.g "Pot", "Soirée Club") and associated properties
+    Type of Activity, (e.g "Pot", "Soirée Club") and associated properties.
+
+    Activity Type are used as a search field for Activity, and determine how
+    some rules about the activity:
+     - Can people be invited
+     - What is the entrance fee.
     """
     name = models.CharField(
         verbose_name=_('name'),
@@ -32,7 +37,9 @@ class ActivityType(models.Model):
 
 class Activity(models.Model):
     """
-    An IRL event organized by a club for others.
+    An IRL event organized by a club for other club.
+
+    By default the invited clubs should be the Club containing all the active accounts.
     """
     name = models.CharField(
         verbose_name=_('name'),
@@ -73,7 +80,7 @@ class Activity(models.Model):
 
 class Guest(models.Model):
     """
-    People who are not current members of any clubs, and invited by someone who is a current member.
+    People who are not current members of any clubs, and are invited by someone who is a current member.
     """
     activity = models.ForeignKey(
         Activity,
@@ -92,6 +99,7 @@ class Guest(models.Model):
         null=True,
     )
     entry_transaction = models.ForeignKey(
+        null=True,
         'note.Transaction',
         on_delete=models.PROTECT,
     )

apps/member/models.py

@@ -13,8 +13,9 @@ class Profile(models.Model):
     """
     An user profile
 
-    We do not want to patch the Django Contrib Auth User class
+    We do not want to patch the Django Contrib :model:`auth.User`model;
     so this model add an user profile with additional information.
+
     """
     user = models.OneToOneField(
         settings.AUTH_USER_MODEL,
@@ -53,7 +54,8 @@ class Profile(models.Model):
 
 class Club(models.Model):
     """
-    A student club
+    A club is a group of people, whose membership is handle by their
+    :model:`member.Membership`, and gives access to right defined by a :model:`member.Role`.
     """
     name = models.CharField(
         verbose_name=_('name'),
@@ -101,7 +103,10 @@ class Club(models.Model):
 
 class Role(models.Model):
     """
-    Role that an user can have in a club
+    Role that an :model:`auth.User` can have in a :model:`member.Club`
+
+    TODO: Integrate the right management, and create some standard Roles at the
+    creation of the club.
     """
     name = models.CharField(
         verbose_name=_('name'),
@@ -117,6 +122,7 @@ class Role(models.Model):
 class Membership(models.Model):
     """
     Register the membership of a user to a club, including roles and membership duration.
+
     """
     user = models.ForeignKey(
         settings.AUTH_USER_MODEL,

apps/note/models/notes.py

@@ -18,7 +18,11 @@ Defines each note types
 
 class Note(PolymorphicModel):
     """
-    An model, use to add transactions capabilities
+    Gives transactions capabilities. Note is a Polymorphic Model, use as based
+    for the models :model:`note.NoteUser` and :model:`note.NoteClub`.
+    A Note principaly store the actual balance of someone/some club.
+    A Note can be searched find throught an :model:`note.Alias`
+
     """
     balance = models.IntegerField(
         verbose_name=_('account balance'),
@@ -94,7 +98,7 @@ class Note(PolymorphicModel):
 
 class NoteUser(Note):
     """
-    A Note associated to an User
+    A :model:`note.Note` associated to an  unique :model:`auth.User`.
     """
     user = models.OneToOneField(
         settings.AUTH_USER_MODEL,
@@ -116,7 +120,7 @@ class NoteUser(Note):
 
 class NoteClub(Note):
     """
-    A Note associated to a Club
+    A :model:`note.Note` associated to an unique :model:`member.Club`
     """
     club = models.OneToOneField(
         'member.Club',
@@ -133,17 +137,18 @@ class NoteClub(Note):
         return str(self.club)
 
     def pretty(self):
-        return _("Note for %(club)s club") % {'club': str(self.club)}
+        return _("Note of %(club)s club") % {'club': str(self.club)}
 
 
 class NoteSpecial(Note):
     """
-    A Note for special account, where real money enter or leave the system
+    A :model:`note.Note` for special accounts, where real money enter or leave the system
     - bank check
     - credit card
     - bank transfer
     - cash
     - refund
+    This Type of Note is not associated to a :model:`auth.User` or :model:`member.Club` .
     """
     special_type = models.CharField(
         verbose_name=_('type'),
@@ -161,7 +166,13 @@ class NoteSpecial(Note):
 
 class Alias(models.Model):
     """
-    An alias labels a Note instance, only for user and clubs
+    points toward  a :model:`note.NoteUser` or :model;`note.NoteClub` instance.
+    Alias are unique, but a :model:`note.NoteUser` or :model:`note.NoteClub` can
+    have multiples aliases.
+
+    Aliases name are also normalized, two differents :model:`note.Note` can not
+    have the same normalized alias, to avoid confusion when referring orally to
+    it.
     """
     name = models.CharField(
         verbose_name=_('name'),

apps/note/models/transactions.py

@@ -15,6 +15,11 @@ Defines transactions
 
 
 class TransactionTemplate(models.Model):
+    """
+    Defined a reccurent transaction
+
+    associated to selling something (a burger, a beer, ...)
+    """
     name = models.CharField(
         verbose_name=_('name'),
         max_length=255,
@@ -44,6 +49,15 @@ class TransactionTemplate(models.Model):
 
 
 class Transaction(models.Model):
+    """
+    General transaction between two :model:`note.Note`
+
+    amount is store in centimes of currency, making it a  positive integer
+    value. (from someone to someone else)
+
+    TODO: Ensure source != destination.
+    """
+
     source = models.ForeignKey(
         Note,
         on_delete=models.PROTECT,
@@ -112,6 +126,11 @@ class Transaction(models.Model):
 
 
 class MembershipTransaction(Transaction):
+    """
+    Special type of :model:`note.Transaction` associated to a :model:`member.Membership`.
+
+    """
+
     membership = models.OneToOneField(
         'member.Membership',
         on_delete=models.PROTECT,