Documentation: quickstart

[skip ci]

docs/detailed_configuration/register.rst

@@ -24,19 +24,27 @@ Assuming that the Django REST registration views are served at
 ``https://backend-host/api/v1/accounts/``
 then the ``register``, ``verify_registration`` views are served as:
 
-* ``https://backend-host/api/v1/accounts/register/``
-* ``https://backend-host/api/v1/accounts/verify-registration/``
+*   ``https://backend-host/api/v1/accounts/register/``
+*   ``https://backend-host/api/v1/accounts/verify-registration/``
 
 accordingly.
 
+.. _register-verification-workflow:
+
 Verification workflow
 ---------------------
 
-We're assuming that the Django REST Registration views are served at
-``https://backend-host/api/v1/accounts/``
-and you configured :ref:`register-verification-url-setting` to be
-``https://frontend-host/verify-user/``
+Let's describe it by example.
+We're assuming that:
+
+-   the Django REST Registration views are served at
+    ``https://backend-host/api/v1/accounts/``
+-   you have :ref:`register-verification-enabled-setting` set to ``True``
+    (this by default)
+-   you configured :ref:`register-verification-url-setting` to be
+    ``https://frontend-host/verify-user/``
 
+Then the verification workflow looks as follows:
 
 1.  The user who wants to register itself sends AJAX POST request to
     ``https://backend-host/api/v1/accounts/register/`` endpoint.

docs/detailed_configuration/register_email.rst

@@ -24,19 +24,27 @@ Assuming that the Django REST Registration views are served at
 ``https://backend-host/api/v1/accounts/``
 then the ``register_email``, ``verify_email`` views are served as:
 
-* ``https://backend-host/api/v1/accounts/register-email/``
-* ``https://backend-host/api/v1/accounts/verify-email/``
+*   ``https://backend-host/api/v1/accounts/register-email/``
+*   ``https://backend-host/api/v1/accounts/verify-email/``
 
 accordingly.
 
+.. _register-email-verification-workflow:
+
 Verification workflow
 ---------------------
 
-We're assuming that the Django REST Registration views are served at
-``https://backend-host/api/v1/accounts/``
-and you configured :ref:`register-email-verification-url-setting` to be
-``https://frontend-host/verify-email/``
+Let's describe it by example.
+We're assuming that:
+
+-   the Django REST Registration views are served at
+    ``https://backend-host/api/v1/accounts/``
+-   you have :ref:`register-email-verification-enabled-setting` set to ``True``
+    (this by default)
+-   you configured :ref:`register-email-verification-url-setting` to be
+    ``https://frontend-host/verify-email/``
 
+Then the verification workflow looks as follows:
 
 1.  The user who wants to register new email (which is currently equivalent
     to changing the e-mail) sends AJAX POST request to

docs/detailed_configuration/reset_password.rst

@@ -24,19 +24,27 @@ Assuming that the Django REST registration views are served at
 ``https://backend-host/api/v1/accounts/``
 then the ``send_reset_password_link``, ``reset_password`` views are served as:
 
-* ``https://backend-host/api/v1/accounts/send-reset-password-link/``
-* ``https://backend-host/api/v1/accounts/reset-password/``
+*   ``https://backend-host/api/v1/accounts/send-reset-password-link/``
+*   ``https://backend-host/api/v1/accounts/reset-password/``
 
 accordingly.
 
+.. _reset-password-verification-workflow:
+
 Verification workflow
 ---------------------
 
-We're assuming that the Django REST Registration views are served at
-``https://backend-host/api/v1/accounts/``
-and you configured :ref:`reset-password-verification-url-setting` to be
-``https://frontend-host/reset-password/``
+Let's describe it by example.
+We're assuming that:
+
+-   the Django REST Registration views are served at
+    ``https://backend-host/api/v1/accounts/``
+-   you have :ref:`reset-password-verification-enabled-setting` set to ``True``
+    (this by default)
+-   you configured :ref:`reset-password-verification-url-setting` to be
+    ``https://frontend-host/reset-password/``
 
+Then the verification workflow looks as follows:
 
 1.  The user who wants to reset his/her password sends AJAX POST request to
     ``https://backend-host/api/v1/accounts/send-reset-password-link/`` endpoint.
@@ -61,7 +69,8 @@ and you configured :ref:`reset-password-verification-url-setting` to be
     - ``timestamp``
     - ``signature``
 
-    and after obtaining the new password it should perform AJAX request to
+    and after obtaining the new password from the user
+    it should perform AJAX request to
     ``https://backend-host/api/v1/accounts/reset-password/``
     via HTTP POST with following JSON payload:
 

docs/index.rst

@@ -6,53 +6,57 @@
 Welcome to Django REST Registration's documentation!
 ====================================================
 
-User registration REST API, based on django-rest-framework.
-
-WARNING: Django REST Registration is only Python 3 compatible.
+User registration REST API, based on Django-REST-Framework.
 
 .. toctree::
-   :maxdepth: 2
+    :maxdepth: 2
+
+    install
+    quickstart
+    detailed_configuration/index
+
+
+Requirements
+------------
 
-   install
-   quickstart
-   detailed_configuration/index
+-   Django (1.10+, 2.0+) and Django-REST-Framework (3.3+)
+-   Python 3.4 or higher (no Python 2 support!)
 
 
 Features
 --------
 
--  Supported views:
-
-   -  registration (sign-up) with verification
-   -  login/logout (sign-in), session- or token-based
-   -  user profile (retrieving / updating)
-   -  reset password
-   -  change password
-   -  register (change) e-mail
-
--  Views are compatible with
-   `django-rest-swagger <https://github.com/marcgibbons/django-rest-swagger>`__
--  Views can be authenticated via session or auth token
--  Modeless (uses the user defined by ``settings.AUTH_USER_MODEL`` and
-   also uses `cryptographic
-   signing <https://docs.djangoproject.com/en/dev/topics/signing/>`__
-   instead of profile models)
--  Uses `password
-   validation <https://docs.djangoproject.com/en/dev/topics/auth/passwords/#password-validation>`__
--  Heavily tested (Above 98% code coverage)
+-   Supported views:
+
+    -   registration (sign-up) with verification
+    -   login/logout (sign-in), session- or token-based
+    -   user profile (retrieving / updating)
+    -   reset password
+    -   change password
+    -   register (change) e-mail
+
+-   Views are compatible with
+    `django-rest-swagger <https://github.com/marcgibbons/django-rest-swagger>`__
+-   Views can be authenticated via session or auth token
+-   Modeless (uses the user defined by ``settings.AUTH_USER_MODEL`` and
+    also uses `cryptographic
+    signing <https://docs.djangoproject.com/en/dev/topics/signing/>`__
+    instead of profile models)
+-   Uses `password
+    validation <https://docs.djangoproject.com/en/dev/topics/auth/passwords/#password-validation>`__
+-   Heavily tested (Above 98% code coverage)
+
 
 Current limitations
 -------------------
 
--  Supports only one email per user (as model field)
--  Heavily based on Django (1.10+, 2.0+) and Django-REST-Framework
-   (3.3+)
--  Python3 only
--  No JWT support
+-   Supports only one email per user (as user model field)
+-   No JWT support (but you can use it along libraries like
+    `django-rest-framework-simplejwt <https://github.com/davesque/django-rest-framework-simplejwt>`__)
 
 
 Indices and tables
 ------------------
 
-* :ref:`genindex`
-* :ref:`search`
+*   :ref:`genindex`
+*   :ref:`search`

docs/install.rst

@@ -1,3 +1,5 @@
+.. _installation:
+
 Installation
 ============
 
@@ -12,3 +14,6 @@ Or install directly from source via GitHub:
 ::
 
     pip install git+https://github.com/apragacz/django-rest-registration
+
+Once you installed Django REST Registration you should configure it
+which is described in :ref:`the next step <quickstart>`.

docs/quickstart.rst

@@ -1,8 +1,17 @@
+.. _quickstart:
+
 Quickstart
 ==========
 
-Then, you should add it to the ``INSTALLED_APPS`` so the app templates
-for notification emails can be accessed:
+Assuming you have installed Django REST Registration
+(more installation options can be found :ref:`here<installation>`):
+
+::
+
+    pip install django-rest-registration
+
+you should add it to the ``INSTALLED_APPS`` in your Django settings
+so the app templates for notification emails can be accessed:
 
 .. code:: python
 
@@ -12,8 +21,8 @@ for notification emails can be accessed:
         'rest_registration',
     )
 
-After that, you can use the urls in your urlconfig, for instance (using
-new Django 2.x syntax):
+After that, you can use the urls in your Django urlconfig, for instance
+(using new Django 2.x syntax):
 
 .. code:: python
 
@@ -32,13 +41,18 @@ new Django 2.x syntax):
 
 In Django 1.x you can use old ``url`` instead of ``path``.
 
+In this example, the Django REST Registraton API views will be served under
+``https://your-backend-host/api/v1/accounts/``.
+Obviously, you can choose different URI path than ``api/v1/accounts/``,
+depending on your preferences.
+
 
 Minimal Configuration
 ---------------------
 
-You can configure ``django-rest-registraton`` using the
-``REST_REGISTRATION`` setting in your django settings (similarly to
-``django-rest-framework``).
+You can configure Django REST Registraton using the
+``REST_REGISTRATION`` setting in your Django settings (similarly to
+Django REST Framework).
 
 If you don't do that, Django system checks will inform you
 about invalid configuration.
@@ -58,11 +72,19 @@ which will satisfy the system checks:
 Preferred Configuration
 -----------------------
 
-The minimal configuration is very limited, because it disables verification
-for new users (``REGISTER_VERIFICATION_ENABLED``), verification
-for e-mail change (``REGISTER_EMAIL_VERIFICATION_ENABLED``) and
-verification for reset password  (``RESET_PASSWORD_VERIFICATION_ENABLED``).
-However, the preferred base configuration would be:
+The minimal configuration is very limited, because it:
+
+-   disables e-mail verification for new users
+    (:ref:`register-verification-enabled-setting`), which means that the user
+    can set the e-mail to one not belonging to him/her,
+-   disables e-mail verification for e-mail change
+    (:ref:`register-email-verification-enabled-setting`), which again means
+    that the user can change the e-mail to one not belonging to him/her,
+-   disabled verification for reset password
+    (:ref:`reset-password-verification-enabled-setting`) which basically
+    disables the ability to reset password.
+
+Therefore, the preferred base configuration would be:
 
 .. code:: python
 
@@ -77,39 +99,29 @@ However, the preferred base configuration would be:
 
 You need to replace ``'https://frontend-host/reset-password/'``
 with the URL on your frontend which will be pointed in the "reset password"
-e-mail. You also need also to replace ``'no-reply@example.com'`` with the
-e-mail address which will be used as the sender of the reset e-mail.
+e-mail. This also applies to the other verification urls above.
+You also need also to replace ``'no-reply@example.com'`` with the
+e-mail address which will be used as the sender of the verification e-mails.
 
-The frontend urls are not provided by the library but should be provided
-by the user of the library, because Django REST Registration is
-frontend-agnostic. The frontend urls will receive parameters as GET
-query and should pass them to corresponding REST API views via HTTP POST
-request.
-
-Let's explain it by example:
-
-we're assuming that the ``django-rest-registration`` views are served at
-https://backend-host/api/v1/accounts/. The frontend endpoint
-https://frontend-host/verify-email/ would receive following GET
-parameters:
-
-- ``user_id``
-- ``email``
-- ``timestamp``
-- ``signature``
+In case when any verification is enabled, your Django application needs to be
+`properly configured so it can send e-mails <https://docs.djangoproject.com/en/dev/topics/email/>`__.
 
-and then it should perform AJAX request to
-https://backend-host/api/v1/accounts/verify-email/ via HTTP POST with
-following JSON payload:
+The frontend urls are not provided by the library but should be provided
+by the user of the library (you), because Django REST Registration is
+frontend-agnostic.
 
-.. code:: javascript
+If you want to understand how the verification workflows work and how the
+provided frontend endpoints should work please read:
 
-    {
-        "user_id": "<user id>",
-        "email": "<email>",
-        "timestamp": "<timestamp>",
-        "signature": "<signature>"
-    }
+-   :ref:`Register
+    verification workflow <register-verification-workflow>`
+-   :ref:`Register e-mail
+    verification workflow <register-email-verification-workflow>`
+-   :ref:`Reset password
+    verification workflow <reset-password-verification-workflow>`
 
-and then show a message to the user depending on the response from
-backend server.
+In most cases, the frontend urls should receive parameters as GET
+query and should pass them to corresponding REST API views via HTTP POST
+request. The one exception is reset password workflow, where the page under
+frontend endpoint should also gather the new password from the user and send
+it along other data via HTTP POST to the REST API endpoint.