docs(mfa): Document adapter class

allauth/mfa/adapter.py

@@ -7,6 +7,12 @@
 
 
 class DefaultMFAAdapter:
+    """The adapter class allows you to override various functionality of the
+    ``allauth.mfa`` app.  To do so, point ``settings.MFA_ADAPTER`` to your own
+    class that derives from ``DefaultMFAAdapter`` and override the behavior by
+    altering the implementation of the methods according to your own need.
+    """
+
     error_messages = {
         "unverified_email": _(
             "You cannot activate two-factor authentication until you have verified your email address."
@@ -16,19 +22,26 @@ class DefaultMFAAdapter:
         ),
         "incorrect_code": _("Incorrect code."),
     }
+    "The error messages that can occur as part of MFA form handling."
 
     def __init__(self, request=None):
         self.request = request
 
-    def get_totp_label(self, user):
+    def get_totp_label(self, user) -> str:
+        """Returns the label used for representing the given user in a TOTP QR
+        code.
+        """
         label = user_email(user)
         if not label:
             label = user_username(user)
         if not label:
             label = str(user)
         return label
 
-    def get_totp_issuer(self):
+    def get_totp_issuer(self) -> str:
+        """Returns the TOTP issuer name that will be contained in the TOTP QR
+        code.
+        """
         issuer = app_settings.TOTP_ISSUER
         if not issuer:
             if allauth_settings.SITES_ENABLED:
@@ -39,14 +52,15 @@ def get_totp_issuer(self):
                 issuer = self.request.get_host()
         return issuer
 
-    def encrypt(self, text):
-        """We need to store secrets such as the TOTP key in the database.  This
+    def encrypt(self, text: str) -> str:
+        """Secrets such as the TOTP key are stored in the database.  This
         hook can be used to encrypt those so that they are not stored in the
         clear in the database.
         """
         return text
 
-    def decrypt(self, encrypted_text):
+    def decrypt(self, encrypted_text: str) -> str:
+        """Counter part of ``encrypt()``."""
         text = encrypted_text
         return text
 

docs/conf.py

@@ -1,3 +1,7 @@
+import os
+import sys
+
+
 # -*- coding: utf-8 -*-
 #
 # django-allauth documentation build configuration file, created by
@@ -38,8 +42,8 @@
 master_doc = "index"
 
 # General information about the project.
-project = u"django-allauth"
-copyright = u"2017, Raymond Penners"
+project = "django-allauth"
+copyright = "2017, Raymond Penners"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -182,8 +186,8 @@
     (
         "index",
         "django-allauth.tex",
-        u"django-allauth Documentation",
-        u"Raymond Penners",
+        "django-allauth Documentation",
+        "Raymond Penners",
         "manual",
     ),
 ]
@@ -217,8 +221,8 @@
     (
         "index",
         "django-allauth",
-        u"django-allauth Documentation",
-        [u"Raymond Penners"],
+        "django-allauth Documentation",
+        ["Raymond Penners"],
         1,
     )
 ]
@@ -236,8 +240,8 @@
     (
         "index",
         "django-allauth",
-        u"django-allauth Documentation",
-        u"Raymond Penners",
+        "django-allauth Documentation",
+        "Raymond Penners",
         "django-allauth",
         "One line description of project.",
         "Miscellaneous",
@@ -252,3 +256,12 @@
 
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 # texinfo_show_urls = 'footnote'
+
+extensions = [
+    "sphinx.ext.autodoc",
+]
+
+sys.path.insert(0, os.path.abspath("../"))
+autodoc_mock_imports = [
+    "allauth.account.utils",
+]

docs/mfa/adapter.rst

@@ -0,0 +1,5 @@
+Adapter
+=======
+
+.. autoclass:: allauth.mfa.adapter.DefaultMFAAdapter
+   :members:

docs/mfa/index.rst

@@ -5,3 +5,4 @@ Multi-Factor Authentication
 
    introduction
    configuration
+   adapter