Merge pull request #294 from grucha/docs_allauth

docs updated with instructions on allauth integration

docs/usage.rst

@@ -112,7 +112,7 @@ them as per the example.
                 )
                 return HttpResponse(status=403)
 
-*urls.py:*::
+*urls.py:* ::
 
     from django.urls import path
     from myapp.views import Login
@@ -120,3 +120,56 @@ them as per the example.
     urlpatterns = [
         path('login/', Login.as_view(), name='login'),
     ]
+
+Integration with django-allauth
+-------------------------------
+
+``axes`` relies on having login information stored under ``AXES_USERNAME_FORM_FIELD`` key
+both in ``request.POST`` and in ``credentials`` dict passed to 
+``user_login_failed`` signal. This is not the case with ``allauth``. 
+``allauth`` always uses ``login`` key in post POST data but it becomes ``username``
+key in ``credentials`` dict in signal handler.
+
+To overcome this you need to use custom login form that duplicates the value
+of ``username`` key under a ``login`` key in that dict 
+(and set ``AXES_USERNAME_FORM_FIELD = 'login'``).
+
+You also need to decorate ``dispatch()`` and ``form_invalid()`` methods 
+of the ``allauth`` login view. By default ``axes`` is patching only the 
+``LoginView`` from ``django.contrib.auth`` app and with ``allauth`` you have to
+do the patching of views yourself.
+
+*settings.py:* ::
+    
+    AXES_USERNAME_FORM_FIELD = 'login'
+
+*forms.py:* ::
+
+    from allauth.account.forms import LoginForm
+
+    class AllauthCompatLoginForm(LoginForm):
+        def user_credentials(self):
+            credentials = super(AllauthCompatLoginForm, self).user_credentials()
+            credentials['login'] = credentials.get('email') or credentials.get('username')
+            return credentials
+
+*urls.py:* ::
+
+    from allauth.account.views import LoginView
+    from axes.decorators import axes_dispatch
+    from axes.decorators import axes_form_invalid
+    from django.utils.decorators import method_decorator
+
+    from my_app.forms import AllauthCompatLoginForm
+
+    LoginView.dispatch = method_decorator(axes_dispatch)(LoginView.dispatch)
+    LoginView.form_invalid = method_decorator(axes_form_invalid)(LoginView.form_invalid)
+
+    urlpatterns = [
+        # ...
+        url(r'^accounts/login/$', # Override allauth's default view with a patched view
+            LoginView.as_view(form_class=AllauthCompatLoginForm),
+            name="account_login"),
+        url(r'^accounts/', include('allauth.urls')),
+        # ...
+    ]