docs: Update docs

docs/index.rst

@@ -13,7 +13,8 @@ Run this command to install django-nopassword::
     pip install django-nopassword
 
 Requirements:
-Django >= 1.4 (1.5 custom user is supported)
+Django >= 1.11 (custom user is supported)
 
 .. include:: usage.rst
+.. include:: rest.rst
 .. include:: settings.rst

docs/rest.rst

@@ -0,0 +1,43 @@
+REST API
+--------
+To use the REST API, *djangorestframework* must be installed::
+
+    pip install djangorestframework
+
+Add rest framework to installed apps::
+
+    INSTALLED_APPS = (
+        ...
+        'rest_framework',
+        'rest_framework.authtoken',
+        'nopassword',
+        ...
+    )
+
+Add *TokenAuthentication* to default authentication classes::
+
+    REST_FRAMEWORK = {
+        'DEFAULT_AUTHENTICATION_CLASSES': (
+            'rest_framework.authentication.TokenAuthentication',
+        )
+    }
+
+Add urls to your *urls.py*::
+
+    urlpatterns = patterns('',
+        ...
+        url(r'^api/accounts/', include('nopassword.rest.urls')),
+        ...
+    )
+
+You will have the following endpoints available:
+
+- `/api/accounts/login/` (POST)
+   - username
+   - next (optional, will be returned in ``/api/accounts/login/code/`` to be handled by the frontend)
+   - Sends a login code to the user
+- `/api/accounts/login/code/` (POST)
+   - code
+   - Returns ``key`` (authentication token) and ``next`` (provided by ``/api/accounts/login/``)
+- `/api/accounts/logout/` (POST)
+   - Performs logout

docs/settings.rst

@@ -12,36 +12,17 @@ django-nopassword settings
 
     Defines how long a login code is valid in seconds.
 
-.. attribute:: NOPASSWORD_NAMESPACE
-
-    Default: ``'nopassword'``
-
-    Defines the namespace for the urls, this must match the namespace of the include of
-    nopassword.urls.
-
-.. attribute:: NOPASSWORD_HIDE_USERNAME
-
-    Default: ``False``
-
-    If set to True, the login url will not contain the username.
-
-.. attribute:: NOPASSWORD_LOGIN_EMAIL_SUBJECT
-
-    Default: ``_('Login code')``
-
-    Sets Email Subject for Login Emails.
-
 .. attribute:: NOPASSWORD_HASH_ALGORITHM
 
     Default: ``'sha256'``
 
     Set the algorithm for used in logincode generation. Possible values are those who are supported in hashlib. The value should be set as the name of the attribute in hashlib. Example `hashlib.sha256()` would be `NOPASSWORD_HASH_ALGORITHM = 'sha256'.
 
-.. attribute:: NOPASSWORD_POST_REDIRECT
+.. attribute:: NOPASSWORD_LOGIN_ON_GET
 
-    Default: ``True``
+    Default: ``False``
 
-    By default, the login code url requires a POST request to authenticate the user. A GET request renders ``registration/login_submit.html``, which contains some Javascript that automatically performs the POST on page load. To authenticate directly inside the initial GET request instead, set this to ``False``.
+    By default, the login code url requires a POST request to authenticate the user. A GET request renders a form that must be submitted by the user to perform authentication. To authenticate directly inside the initial GET request instead, set this to ``True``.
 
 .. attribute:: NOPASSWORD_CODE_LENGTH
 
@@ -66,15 +47,6 @@ django-nopassword settings
 Django settings used in django-nopassword
 +++++++++++++++++++++++++++++++++++++++++
 
-.. attribute:: SERVER_URL
-
-    Default: ``'example.com'``
-
-    By default, ``nopassword.views.login`` passes the result of ``result.get_host()`` to
-    ``LoginCode.send_login_code`` to build the login URL. If you write your own view
-    and/or want to avoid this behavior by not passing a value for host, the
-    ``SERVER_URL`` setting will be used instead.
-
 .. attribute:: DEFAULT_FROM_EMAIL
 
     Default: ``'root@example.com'``

docs/usage.rst

@@ -6,22 +6,22 @@ Add the app to installed apps::
         'nopassword',
     )
 
-Set the authentication backend to *EmailBackend*::
+Add the authentication backend *EmailBackend*::
 
-    AUTHENTICATION_BACKENDS = ( 'nopassword.backends.email.EmailBackend', )
+    AUTHENTICATION_BACKENDS = (
+        # Needed to login by username in Django admin, regardless of `nopassword`
+        'django.contrib.auth.backends.ModelBackend',
+
+        # Send login codes via email
+        'nopassword.backends.email.EmailBackend',
+    )
 
 Add urls to your *urls.py*::
 
     urlpatterns = patterns('',
         url(r'^accounts/', include('nopassword.urls')),
     )
 
-Verify users
-~~~~~~~~~~~~
-If it is necessary to verify that users still are active in another system. Override
-*verify_user(user)* to implement your check. In *NoPasswordBackend* that method checks
-whether the user is active in the django app.
-
 Backends
 ++++++++
 There are several predefined backends. Usage of those backends are listed below.
@@ -30,33 +30,36 @@ There are several predefined backends. Usage of those backends are listed below.
 
 .. class:: EmailBackend
 Delivers the code by email. It uses the django send email functionality to send
-the emails. It will attach both HTML and plain-text versions of the email.
+the emails.
+
+Override the following templates to customize emails:
+
+- ``registration/login_email.txt`` - Plain text message
+- ``registration/login_email.html`` - HTML message (note that no default html message is attached)
+- ``registration/login_subject.txt`` - Subject
 
 .. currentmodule:: nopassword.backends.sms
 
 .. class:: TwilioBackend
 Delivers the code by sms sent through the twilio service.
 
+Override the following template to customize messages:
+
+- ``registration/login_sms.txt`` - SMS message
+
 
 Custom backends
 ~~~~~~~~~~~~~~~
 In backends.py there is a *NoPasswordBackend*, from which it is possible
 to build custom backends. The *EmailBackend* described above inherits from
-this backend. Creating your own backend is can be done by creating a subclass
-of *NoPasswordBackend* and implementing *send_login_code*. A good example is
-the *EmailBackend*::
-
-    class EmailBackend(NoPasswordBackend):
-
-        def send_login_code(self, code, secure=False, host=None):
-            subject = getattr(settings, 'NOPASSWORD_LOGIN_EMAIL_SUBJECT', _('Login code'))
-            to_email = [code.user.email]
-            from_email = getattr(settings, 'DEFAULT_FROM_EMAIL', 'root@example.com')
-
-            context = {'url': code.login_url(secure=secure, host=host), 'code': code}
-            text_content = render_to_string('registration/login_email.txt', context)
-            html_content = render_to_string('registration/login_email.html', context)
-
-            msg = EmailMultiAlternatives(subject, text_content, from_email, to_email)
-            msg.attach_alternative(html_content, 'text/html')
-            msg.send()
+this backend. Creating your own backend can be done by creating a subclass
+of *NoPasswordBackend* and implementing *send_login_code*.::
+
+    class CustomBackend(NoPasswordBackend):
+    
+        def send_login_code(self, code, context, **kwargs):
+            """
+            Use code.user to get contact information
+            Use context to render a custom template
+            Use kwargs in case you have a custom view that provides additional configuration
+            """