James Bennett avatar James Bennett committed c390a7b

Some more documentation updates.

Comments (0)

Files changed (3)

docs/backend-api.rst

 
 At its core, django-registration is built around the idea of pluggable
 backends which can implement different workflows for user
-registration. Although the default backend uses a common two-phase
-system (registration followed by activation), backends are generally
-free to implement any workflow desired by their authors.
+registration. Although :ref:`the default backend <default-backend>`
+uses a common two-phase system (registration followed by activation),
+backends are generally free to implement any workflow desired by their
+authors.
 
 This is deliberately meant to be complementary to Django's own
 `pluggable authentication backends
     The backend class.
 
 ``user``
-    The ``User`` instance representing the new account.
+    The ``User`` instance representing the activated account.
 
 ``request``
     The ``HttpRequest`` in which the user activated.

docs/default-backend.rst

 ===================
 
 A default :ref:`registration backend <backend-api>` is bundled with
-django-registration in the module ``registration.backends.default``,
-and implements a simple two-step workflow in which a new user first
-registers, then confirms and activates the new account by following a
-link sent to the email address supplied during registration.
+django-registration, as the class
+``registration.backends.default.DefaultBackend``, and implements a
+simple two-step workflow in which a new user first registers, then
+confirms and activates the new account by following a link sent to the
+email address supplied during registration.
 
 
 Default behavior and configuration
 How account data is stored for activation
 -----------------------------------------
 
-During registration, a new user account is created, with the
-``is_active`` field set to ``False``. An email is then sent to the
-email address of the account, containing a link the user must click to
-activate the account; at that point the ``is_active`` field is set to
-``True``, and the user may log in normally.
+During registration, a new instance of
+``django.contrib.auth.models.User`` is created to represent the new
+account, with the ``is_active`` field set to ``False``. An email is
+then sent to the email address of the account, containing a link the
+user must click to activate the account; at that point the
+``is_active`` field is set to ``True``, and the user may log in
+normally.
 
-Activation is handled by generating a storing an activation key in the
-database, using the following model:
+Activation is handled by generating and storing an activation key in
+the database, using the following model:
 
 
 .. currentmodule:: registration.models
    .. attribute:: activation_key
 
       A 40-character ``CharField``, storing the activation key for the
-      account. Initially, the activation key is a SHA1 hash generated
-      from combining the username of the account with a
-      randomly-generated salt; after activation, this is reset to
-      :attr:`ACTIVATED`.
+      account. Initially, the activation key is the hexdigest of a
+      SHA1 hash; after activation, this is reset to :attr:`ACTIVATED`.
 
    Additionally, one class attribute exists:
 
       Creates and returns a :class:`RegistrationProfile` instance for
       the account represented by ``user``.
 
+      The ``RegistrationProfile`` created by this method will have its
+      :attr:`~RegistrationProfile.activation_key` set to a SHA1 hash
+      generated from a combination of the account's username and a
+      random salt.
+
       :param user: The user account; an instance of
          ``django.contrib.auth.models.User``.
       :type user: ``User``
     this file, you can view it online at
     <http://bitbucket.org/ubernostrum/django-registration/src/tip/LICENSE>.
 
+**Why are the forms and models for the default backend not in the default backend?**
+    The model and manager used by :ref:`the default backend
+    <default-backend>` are in ``registration.models``, and the default
+    form class (and various subclasses) are in ``registration.forms``;
+    logically, they might be expected to exist in
+    ``registration.backends.default``, but there are several reasons
+    why that's not such a good idea:
+
+    1. Older versions of django-registration made use of the model and
+       form classes, and moving them would create an unnecessary
+       backwards incompatibility: ``import`` statements would need to
+       be changed, and some database updates would be needed to
+       reflect the new location of the
+       :class:`~registration.models.RegistrationProfile` model.
+
+    2. Due to the design of Django's ORM, the ``RegistrationProfile``
+       model would end up with an ``app_label`` of ``default``, which
+       isn't particularly descriptive and may conflict with other
+       applications. By keeping it in ``registration.models``, it
+       retains an ``app_label`` of ``registration``, which more
+       accurately reflects what it does and is less likely to cause
+       problems.
+
+    3. Although the ``RegistrationProfile`` model and the various
+       :ref:`form classes <forms>` are used by the default backend,
+       they can and are meant to be reused as needed by other
+       backends. Any backend which uses an activation step should feel
+       free to reuse the ``RegistrationProfile`` model, for example,
+       and the registration form classes are in no way tied to a
+       specific backend (and cover a number of common use cases which
+       will crop up regardless of the specific backend logic in use).
+
 
 Installation and setup
 ----------------------
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.