Improve documentation

Author: codingjoe

README.rst

@@ -38,8 +38,7 @@ Installation
 
 Run this command to install ``django-mail-auth``::
 
-    pip install django-mail-auth
-
+    python3 -m pip install django-mail-auth[wagtail]
 
 Setup
 -----
@@ -50,8 +49,10 @@ First add ``mailauth`` to you installed apps::
         # Django's builtin apps…
 
         'mailauth',
+
         'mailauth.contrib.admin',  # optional
         'mailauth.contrib.user',  # optional
+
         # optional, must be included before "wagtail.admin"
         'mailauth.contrib.wagtail',
 
@@ -65,8 +66,14 @@ with token based authentication too.
 ``mailauth.contrib.user`` is optional and provides a new Django User model.
 The new User model needs to be enabled via the ``AUTH_USER_MODEL`` setting::
 
+    # This setting should be either "EmailUser" or
+    # any custom subclass of "AbstractEmailUser"
     AUTH_USER_MODEL = 'mailauth_user.EmailUser'
 
+    # optional, Wagtail only
+    WAGTAILUSERS_PASSWORD_ENABLED = False
+
+
 Next you will need to add the new authentication backend::
 
     AUTHENTICATION_BACKENDS = (
@@ -89,6 +96,7 @@ Last but not least, go to your URL root config ``urls.py`` and add the following
 
     urlpatterns = [
         path('accounts/', include('mailauth.urls')),
+
         # optional, must be before "wagtail.admin.urls"
         path('', include('mailauth.contrib.wagtail.urls')),
     ]

docs/conf.py

@@ -28,3 +28,8 @@
     'django': ('https://docs.djangoproject.com/en/stable/',
                'https://docs.djangoproject.com/en/stable/_objects/'),
 }
+
+
+autodoc_default_options = {
+    'show-inheritance': True,
+}

docs/customizing.rst

@@ -2,8 +2,11 @@
 Customizing
 ===========
 
-Django Mail Auth can be easily extend. Besides template adaptations it is
-possible to send send different messages like SMS. To make those changes you
+Custom login message (like SMS)
+_______________________________
+
+Django Mail Auth can be easily extended. Besides template adaptations it is
+possible to send different messages like SMS. To make those changes, you
 will need to write a custom login form.
 
 Custom login form
@@ -76,3 +79,46 @@ API documentation
 
 .. autoclass:: mailauth.forms.BaseLoginForm
     :members:
+
+Custom User Model
+_________________
+
+For convenience, Django Mail Auth provides a
+:class:`EmailUser<mailauth.contrib.user.models.EmailUser>` which is almost
+identical to Django's built in :class:`User<django.contrib.auth.models.User>`
+but without the :attr:`password<django.contrib.auth.models.User.password>`
+and :attr:`username<django.contrib.auth.models.User.username>` field.
+The :attr:`email<mailauth.contrib.user.models.AbstractEmailUser.email>`
+field serves as a username and is – different to Django's User –
+unique and case insensitive.
+
+Implementing a custom User model
+--------------------------------
+
+.. code-block:: python
+
+    from mailauth.contrib.user.models import AbstractEmailUser
+    from phonenumber_field.modelfields import PhoneNumberField
+
+
+    class SMSUser(AbstractEmailUser):
+        phone_number = phone = PhoneNumberField(_("phone number"), unique=True, db_index=True)
+
+    class Meta(AbstractEmailUser.Meta):
+        verbose_name = _("user")
+        verbose_name_plural = _("users")
+        swappable = "AUTH_USER_MODEL"
+
+.. note:: Do not forget to adjust your ``AUTH_USER_MODEL`` to correct ``app_label.ModelName``.
+
+API documentation
+-----------------
+
+.. autoclass:: mailauth.contrib.user.models.AbstractEmailUser
+    :members:
+
+    .. autoattribute:: mailauth.contrib.user.models.AbstractEmailUser.email
+    .. autoattribute:: mailauth.contrib.user.models.AbstractEmailUser.session_salt
+
+.. autoclass:: mailauth.contrib.user.models.EmailUser
+    :members:

mailauth/contrib/user/models.py

@@ -42,13 +42,17 @@ class AbstractEmailUser(AbstractUser):
     USERNAME_FIELD = 'email'
     REQUIRED_FIELDS = []
 
-    email = CIEmailField(_('email address'), unique=True, db_index=True)
     username = None
     password = None
+
+    email = CIEmailField(_('email address'), unique=True, db_index=True)
+    """The field is unique and case insensitive to serve as a better username."""
+
     session_salt = models.CharField(
         max_length=12, editable=False,
         default=get_random_string,
     )
+    """Salt for the session hash replacing the password in this function."""
 
     def has_usable_password(self):
         return False