Updated register configuration docs

apragacz · Feb 19, 2019 · 50dff5c · 50dff5c
1 parent bc0bbc1
commit 50dff5c
Show file tree

Hide file tree

Showing 3 changed files with 79 additions and 6 deletions.
diff --git a/docs/detailed_configuration/register.rst b/docs/detailed_configuration/register.rst
@@ -4,6 +4,21 @@ Registration
 API Views
 ---------
 
+There are two views used in the registration workflow:
+
+.. autofunction:: rest_registration.api.views.register
+
+.. autofunction:: rest_registration.api.views.verify_registration
+
+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/
+
+accordingly.
+
 List of settings
 ----------------
 

diff --git a/docs/detailed_configuration/settings_fields.j2 b/docs/detailed_configuration/settings_fields.j2
@@ -12,8 +12,8 @@ Default:
 {% else %}
 Default: ``{{ f.default|pprint }}``
 {% endif %}
-{% if f.help %}
-{{ f.help }}
+{% if f.sphinx_docstring %}
+{{ f.sphinx_docstring }}
 {% else %}
 No description available, please add it!
 {% endif %}

diff --git a/rest_registration/settings_fields.py b/rest_registration/settings_fields.py
@@ -1,6 +1,8 @@
 import datetime
 from collections import OrderedDict, namedtuple
 
+from rest_registration.utils.text import detect_indent_num, deindent
+
 _Field = namedtuple('_Field', [
     'name',
     'default',
@@ -16,6 +18,12 @@ def __new__(cls, name, *, default=None, help=None, import_string=False):
             cls, name=name, default=default,
             help=help, import_string=import_string)
 
+    @property
+    def sphinx_docstring(self):
+        docstring = self.help if self.help else ''
+        indent_num = detect_indent_num(docstring)
+        return deindent(docstring, indent_num)
+
 
 USER_SETTINGS_FIELDS = [
     Field('USER_LOGIN_FIELDS'),
@@ -41,24 +49,74 @@ def __new__(cls, name, *, default=None, help=None, import_string=False):
         'REGISTER_SERIALIZER_CLASS',
         default='rest_registration.api.serializers.DefaultRegisterUserSerializer',  # noqa: E501,
         import_string=True,
+        help="""
+            The default serializer used by register endpoint.
+            It is used to validate the input data and save (create)
+            the newly registered user. You can use your custom serializer
+            to customise validation logic and the way the user is created
+            in the database.
+            """,
+    ),
+    Field(
+        'REGISTER_SERIALIZER_PASSWORD_CONFIRM',
+        default=True,
+        help="""
+            Used by ``DefaultRegisterUserSerializer``.
+            If ``True``, the serializer requires
+            additional field ``password_confirm`` which value should be
+            the same as the value of ``password`` field.
+
+            It may be useful to disable it if you perform password confirmation
+            at the frontend level.
+            """,
     ),
-    Field('REGISTER_SERIALIZER_PASSWORD_CONFIRM', default=True),
 
     Field(
         'REGISTER_OUTPUT_SERIALIZER_CLASS',
         default='rest_registration.api.serializers.DefaultUserProfileSerializer',  # noqa: E501,
         import_string=True,
+        help="""
+            The default serializer used by register endpoint.
+            It is used output the data associated with
+            the newly registered user. You can use your custom serializer
+            to customise the output representation of the user.
+            """,
     ),
 
-    Field('REGISTER_VERIFICATION_ENABLED', default=True),
-    Field('REGISTER_VERIFICATION_PERIOD', default=datetime.timedelta(days=7)),
-    Field('REGISTER_VERIFICATION_URL'),
+    Field(
+        'REGISTER_VERIFICATION_ENABLED',
+        default=True,
+        help="""
+            If enabled, then newly registered user will not
+            be verified (user field specified by
+            ``USER_VERIFICATION_FLAG_FIELD`` will be false),
+            and verification e-mail with activation link
+            will be sent to the user email (specified by ``USER_EMAIL_FIELD``).
+            """,
+    ),
+    Field(
+        'REGISTER_VERIFICATION_PERIOD',
+        default=datetime.timedelta(days=7),
+        help="""
+            Specifies how long the activation link will be valid.
+            """,
+    ),
+    Field(
+        'REGISTER_VERIFICATION_URL',
+        help="""
+            Frontend URL to which the query parameters will be appended
+            to create the activation link for newly registered user.
+            """,
+    ),
     Field(
         'REGISTER_VERIFICATION_EMAIL_TEMPLATES',
         default={
             'subject': 'rest_registration/register/subject.txt',
             'body': 'rest_registration/register/body.txt',
         },
+        help="""
+            Directory of templates used to generate the verification email.
+            """,
     ),
 ]