Improve docs for attempt tracking, resets, and customization

Fixes #433

CHANGES.rst

@@ -11,6 +11,9 @@ Changes
   Deprecate ``axes.request.AxesHttpRequest`` object type definition.
   [aleksihakli]
 
+- Improve documentation on attempt tracking, resets, and customization.
+  [aleksihakli]
+
 
 5.0.4 (2019-05-09)
 ------------------

docs/3_usage.rst

@@ -7,13 +7,82 @@ Once Axes is is installed and configured, you can login and logout
 of your application via the ``django.contrib.auth`` views.
 The attempts will be logged and visible in the Access Attempts section in admin.
 
-By default, Axes will lock out repeated access attempts from the same IP address.
-You can allow this IP to attempt again by deleting relevant AccessAttempt records.
+Axes monitors the views by using the Django login and logout signals and
+locks out user attempts with a custom authentication backend that checks
+if requests are allowed to authenticate per the configured rules.
 
-Records can be deleted, for example, by using the Django admin application.
+By default, Axes will lock out repeated access attempts from the same IP address
+by monitoring login failures and storing them into the default database.
 
-You can also use the ``axes_reset``, ``axes_reset_ip``, and ``axes_reset_username``
-management commands with the Django ``manage.py`` command helpers:
+
+Authenticating users
+--------------------
+
+Axes needs a ``request`` attribute to be supplied to the stock Django ``authenticate``
+method in the ``django.contrib.auth`` module in order to function correctly.
+
+If you wish to manually supply the argument to the calls to ``authenticate``,
+you can use the following snippet in your custom login views, tests, or other code::
+
+
+    def custom_login_view(request)
+        username = ...
+        password = ...
+
+        user = authenticate(
+            request=request,  # this is the important custom argument
+            username=username,
+            password=password,
+        )
+
+        if user is not None:
+            login(request, user)
+
+
+If your test setup has problems with the ``request`` argument, you can either
+supply the argument manually with a blank `HttpRequest()`` object,
+disable Axes in the test setup by excluding ``axes`` from ``INSTALLED_APPS``,
+or leave out ``axes.backends.AxesBackend`` from your ``AUTHENTICATION_BACKENDS``.
+
+If you are using a 3rd party library that does not supply the ``request`` attribute
+when calling ``authenticate`` you can implement a customized backend that inherits
+from ``axes.backends.AxesBackend`` or other backend and overrides the ``authenticate`` method.
+
+
+Resetting attempts and lockouts
+-------------------------------
+
+When Axes locks an IP address, it is not allowed to login again.
+You can allow IPs to attempt again by resetting (deleting)
+the relevant AccessAttempt records.
+
+You can also configure automatic cool down periods, IP whitelists and blacklists
+and even custom programmatic functions for the lockouts. Please check out the
+configuration and customization documentation for further information.
+
+.. note::
+   Please note that the functionality describe here concerns the default
+   database attempt tracker and handler. If you have customized or changed
+   the default handler to another class such as the cache handler,
+   you have to implement custom reset commands for it.
+
+
+Resetting attempts from the Django admin UI
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Records can be easily deleted by using the Django admin application.
+
+Go to the admin UI and check the ``Access Attempt`` view.
+Select the attempts you wish the allow again and simply remove them.
+The blocked user will be allowed to log in again in accordance to the rules.
+
+
+Resetting attempts from command line
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Axes offers a command line interface with
+``axes_reset``, ``axes_reset_ip``, and ``axes_reset_username``
+management commands with the Django ``manage.py`` or ``django-admin`` command helpers:
 
 - ``python manage.py axes_reset``
   will reset all lockouts and access records.
@@ -22,6 +91,10 @@ management commands with the Django ``manage.py`` command helpers:
 - ``python manage.py axes_reset_username [username ...]``
   will clear lockouts and records for the given usernames.
 
+
+Resetting attempts programmatically by APIs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 In your code, you can use the ``axes.utils.reset`` function.
 
 - ``reset()`` will reset all lockouts and access records.