James Bennett avatar James Bennett committed c3bdf9d

Remove old documentation to make way for the new.

Comments (0)

Files changed (4)

docs/forms.txt

-=====
-Forms
-=====
-
-
-To ease and automate the process of validating user information during
-registration, several form classes (built using Django's `forms
-library`_) are provided: a base ``RegistrationForm`` and subclasses
-which provide specific customized functionality. All of the forms
-described below are found in ``registration.forms``.
-
-.. _forms library: http://docs.djangoproject.com/en/dev/topics/forms/
-
-
-``RegistrationForm``
-====================
-
-Form for registering a new user account.
-
-Validates that the requested username is not already in use, and
-requires the password to be entered twice to catch typos.
-
-Subclasses should feel free to add any additional validation they
-need, but should either preserve the base ``save()`` or implement a
-``save()`` method which returns a ``User``.
-    
-Fields:
-
-``username``
-    The new user's requested username. Will be validated according to
-    the same regular expression Django's authentication system uses to
-    validate usernames.
-
-``email``
-    The new user's email address. Must be a well-formed email address.
-
-``password1``
-    The new user's password.
-
-``password2``
-    The password, again, to catch typos.
-
-
-Non-validation methods:
-
-``save()``
-    Creates the new ``User`` and ``RegistrationProfile``, and returns
-    the ``User`` (by calling
-    ``RegistrationProfile.objects.create_inactive_user()``).
-
-
-Subclasses of ``RegistrationForm``
-==================================
-
-As explained above, subclasses may add any additional validation they
-like, but must either preserve the ``save()`` method or implement a
-``save()`` method with an identical signature.
-
-Three subclasses are included as examples, and as ready-made
-implementations of useful customizations:
-
-``RegistrationFormTermsOfService``
-    Subclass of ``RegistrationForm`` which adds a required checkbox
-    for agreeing to a site's Terms of Service.
-
-``RegistrationFormUniqueEmail``
-    Subclass of ``RegistrationForm`` which enforces uniqueness of
-    email addresses.
-
-``RegistrationFormNoFreeEmail``
-    Subclass of ``RegistrationForm`` which disallows registration with
-    email addresses from popular free webmail services; moderately
-    useful for preventing automated spam registrations.
-    
-    To change the list of banned domains, subclass this form and
-    override the attribute ``bad_domains``.

docs/models.txt

-===================
-Models and managers
-===================
-
-
-Because the two-step process of registration and activation requires
-some means of temporarily storing activation key and retrieving it for
-verification, a simple model --
-``registration.models.RegistrationProfile`` -- is provided in this
-application, and a custom manager --
-``registration.models.RegistrationManager`` -- is included and defines
-several useful methods for interacting with ``RegistrationProfile``.
-
-Both the ``RegistrationProfile`` model and the ``RegistrationManager``
-are found in ``registration.models``.
-
-
-The ``RegistrationProfile`` model
-=================================
-
-A simple profile which stores an activation key for use during user
-account registration.
-
-Generally, you will not want to interact directly with instances of
-this model; the provided manager includes methods for creating and
-activating new accounts, as well as for cleaning out accounts which
-have never been activated.
-
-While it is possible to use this model as the value of the
-``AUTH_PROFILE_MODULE`` setting, it's not recommended that you do
-so. This model's sole purpose is to store data temporarily during
-account registration and activation, and a mechanism for automatically
-creating an instance of a site-specific profile model is provided via
-the ``create_inactive_user`` on ``RegistrationManager``.
-    
-``RegistrationProfile`` objects have the following fields:
-
-``activation_key``
-    A SHA1 hash used as an account's activation key.
-
-``user``
-    The ``User`` object for which activation information is being
-    stored.
-
-``RegistrationProfile`` also has one custom method defined:
-
-``activation_key_expired()``
-    Determines whether this ``RegistrationProfile``'s activation key
-    has expired.
-    
-    Returns ``True`` if the key has expired, ``False`` otherwise.
-    
-    Key expiration is determined by a two-step process:
-    
-    1. If the user has already activated, the key will have been reset
-       to the string constant ``ACTIVATED``. Re-activating is not
-       permitted, and so this method returns ``True`` in this case.
-    
-    2. Otherwise, the date the user signed up is incremented by the
-       number of days specified in the setting
-       ``ACCOUNT_ACTIVATION_DAYS`` (which should be the number of days
-       after signup during which a user is allowed to activate their
-       account); if the result is less than or equal to the current
-       date, the key has expired and this method returns ``True``.
-
-
-The ``RegistrationManager``
-===========================
-
-Custom manager for the ``RegistrationProfile`` model.
-    
-The methods defined here provide shortcuts for account creation and
-activation (including generation and emailing of activation keys), and
-for cleaning out expired inactive accounts.
-    
-Methods:
-
-``activate_user(activation_key)``
-    Validate an activation key and activate the corresponding
-    ``User`` if valid.
-    
-    If the key is valid and has not expired, return the ``User``
-    after activating.
-    
-    If the key is not valid or has expired, return ``False``.
-    
-    If the key is valid but the ``User`` is already active,
-    return ``False``.
-    
-    To prevent reactivation of an account which has been
-    deactivated by site administrators, the activation key is
-    reset to the string constant ``RegistrationProfile.ACTIVATED``
-    after successful activation.
-
-    To execute customized logic when a ``User`` is activated,
-    connect a function to the signal
-    ``registration.signals.user_activated``; this signal will be
-    sent (with the ``User`` as the value of the keyword argument
-    ``user``) after a successful activation.
-
-``create_inactive_user(username, password, email, send_email=True)``
-    Create a new, inactive ``User``, generate a
-    ``RegistrationProfile`` and email its activation key to the
-    ``User``, returning the new ``User``.
-    
-    To disable the email, call with ``send_email=False``.
-
-    The activation email will make use of two templates:
-
-    ``registration/activation_email_subject.txt``
-        This template will be used for the subject line of the
-        email. It receives one context variable, ``site``, which
-        is the currently-active
-        ``django.contrib.sites.models.Site`` instance. Because it
-        is used as the subject line of an email, this template's
-        output **must** be only a single line of text; output
-        longer than one line will be forcibly joined into only a
-        single line.
-
-    ``registration/activation_email.txt``
-        This template will be used for the body of the email. It
-        will receive three context variables: ``activation_key``
-        will be the user's activation key (for use in constructing
-        a URL to activate the account), ``expiration_days`` will
-        be the number of days for which the key will be valid and
-        ``site`` will be the currently-active
-        ``django.contrib.sites.models.Site`` instance.
-
-    To execute customized logic once the new ``User`` has been
-    created, connect a function to the signal
-    ``registration.signals.user_registered``; this signal will be
-    sent (with the new ``User`` as the value of the keyword
-    argument ``user``) after the ``User`` and
-    ``RegistrationProfile`` have been created, and after the email (if
-    any) has been sent.
-        
-``create_profile(user)``
-    Creates a ``RegistrationProfile`` for a given ``User``. Returns
-    the ``RegistrationProfile``.
-    
-    The activation key for the ``RegistrationProfile`` will be a SHA1
-    hash, generated from a combination of the ``User``'s username and
-    a random salt.
-
-``deleted_expired_users()``
-    Removes expired instances of ``RegistrationProfile`` and their
-    associated ``User`` objects.
-    
-    Accounts to be deleted are identified by searching for instances
-    of ``RegistrationProfile`` with expired activation keys, and then
-    checking to see if their associated ``User`` instances have the
-    field ``is_active`` set to ``False``; any ``User`` who is both
-    inactive and has an expired activation key will be deleted.
-    
-    It is recommended that this method be executed regularly as part
-    of your routine site maintenance; this application provides a
-    custom management command which will call this method, accessible
-    as ``manage.py cleanupregistration``.
-    
-    Regularly clearing out accounts which have never been activated
-    serves two useful purposes:
-    
-    1. It alleviates the ocasional need to reset a
-       ``RegistrationProfile`` and/or re-send an activation email when
-       a user does not receive or does not act upon the initial
-       activation email; since the account will be deleted, the user
-       will be able to simply re-register and receive a new activation
-       key.
-    
-    2. It prevents the possibility of a malicious user registering one
-       or more accounts and never activating them (thus denying the
-       use of those usernames to anyone else); since those accounts
-       will be deleted, the usernames will become available for use
-       again.
-    
-    If you have a troublesome ``User`` and wish to disable their
-    account while keeping it in the database, simply delete the
-    associated ``RegistrationProfile``; an inactive ``User`` which
-    does not have an associated ``RegistrationProfile`` will not be
-    deleted.

docs/overview.txt

-===================
-Django registration
-===================
-
-
-This is a fairly simple user-registration application for Django_,
-designed to make allowing user signups as painless as possible.
-
-.. _Django: http://www.djangoproject.com/
-
-
-Overview
-========
-
-This application enables a common user-registration workflow:
-
-1. User fills out a registration form, selecting a username and
-   password and entering an email address.
-
-2. An inactive account is created, and an activation link is sent to
-   the user's email address.
-
-3. User clicks the activation link, the account becomes active and the
-   user is able to log in and begin contributing to your site.
-
-Various methods of extending and customizing the registration process
-are also provided.
-
-
-Installation
-============
-
-In order to use django-registration, you will need to have a
-functioning installation of Django 1.0 or newer; due to changes needed
-to stabilize Django's APIs prior to the 1.0 release,
-django-registration will not work with older releases of Django.
-
-There are three basic ways to install django-registration:
-automatically installing a package using Python's package-management
-tools, manually installing a package, and installing from a Mercurial
-checkout.
-
-
-Using a package-management tool
--------------------------------
-
-The easiest way by far to install django-registration and most other
-interesting Python software is by using an automated
-package-management tool, so if you're not already familiar with the
-available tools for Python, now's as good a time as any to get
-started.
-
-The most popular option currently is `easy_install`_; refer to its
-documentation to see how to get it set up. Once you've got it, you'll
-be able to simply type::
-
-    easy_install django-registration
-
-And it will handle the rest.
-
-Another option that's currently gaining steam (and which I personally
-prefer for Python package management) is `pip`_. Once again, you'll
-want to refer to its documentation to get up and running, but once you
-have you'll be able to type::
-
-    pip install django-registration
-
-And you'll be done.
-
-
-Manually installing the 0.7 package
------------------------------------
-
-If you'd prefer to do things the old-fashioned way, you can manually
-download the `django-registration 0.7 package`_ from the Python
-Package Index. This will get you a file named
-"django-registration-0.7.tar.gz" which you can unpack (double-click on
-the file on most operating systems) to create a directory named
-"django-registration-0.7". Inside will be a script named "setup.py";
-running::
-
-    python setup.py install
-
-will install django-registration (though keep in mind that this
-defaults to a system-wide installation, and so may require
-administrative privileges on your computer).
-
-
-Installing from a Mercurial checkout
-------------------------------------
-
-If you have `Mercurial`_ installed on your computer, you can also
-obtain a complete copy of django-registration by typing::
-
-    hg clone http://bitbucket.org/ubernostrum/django-registration/
-
-Inside the resulting "django-registration" directory will be a
-directory named "registration", which is the actual Python module for
-this application; you can symlink it from somewhere on your Python
-path. If you prefer, you can use the setup.py script in the
-"django-registration" directory to perform a normal installation, but
-using a symlink offers easy upgrades: simply running ``hg pull -u``
-inside the django-registration directory will fetch updates from the
-main repository and apply them to your local copy.
-
-
-.. _easy_install: http://peak.telecommunity.com/DevCenter/EasyInstall
-.. _pip: http://pypi.python.org/pypi/pip/
-.. _django-registration 0.7 package: http://pypi.python.org/pypi/django-registration/0.7
-.. _Mercurial: http://www.selenic.com/mercurial/wiki/
-
-
-Basic use
-=========
-
-To use the registration system with all its default settings, you'll
-need to do the following:
-
-1. Add ``registration`` to the ``INSTALLED_APPS`` setting of your
-   Django project.
-
-2. Add the setting ``ACCOUNT_ACTIVATION_DAYS`` to your settings file;
-   this should be the number of days activation keys will remain valid
-   after an account is registered.
-
-3. Create the necessary templates (see the section on templates below
-   for details).
-
-4. Add this line to your site's root URLConf::
-   
-       (r'^accounts/', include('registration.urls')),
-
-5. Link people to ``/accounts/register/`` so they can start signing
-   up. Using the default URLConf will also automatically set up the
-   authentication-oriented views in ``django.contrib.auth`` for you,
-   so if you use it you can point people to, e.g.,
-   ``/accounts/login/`` to log in.
-
-
-Templates used by django-registration
-=====================================
-
-The views included in django-registration make use of five templates:
-
-* ``registration/registration_form.html`` displays the registration
-  form for users to sign up.
-
-* ``registration/registration_complete.html`` is displayed after the
-  activation email has been sent, to tell the new user to check
-  his/her email.
-
-* ``registration/activation_email_subject.txt`` is used for the
-  subject of the activation email.
-
-* ``registration/activation_email.txt`` is used for the body of the
-  activation email.
-
-* ``registration/activate.html`` is displayed when a user attempts to
-  activate his/her account.
-
-Examples of all of these templates are not provided; you will need to
-create them yourself. For views defined in this application, see the
-included `views documentation`_ for details on available context
-variables, and for details on the templates used by the activation
-email see the included `models documentation`_.
-
-Additionally, the URLConf provided with django-registration includes
-URL patterns for useful views in Django's built-in authentication
-application -- this means that a single ``include`` in your root
-URLConf can wire up registration and the auth application's login,
-logout, and password change/reset views. If you choose to use these
-views you will need to provide your own templates for them; consult
-`the Django authentication documentation`_ for details on the
-templates and contexts used by these views.
-
-.. _views documentation: views.txt
-.. _models documentation: models.txt
-.. _the Django authentication documentation: http://www.djangoproject.com/documentation/authentication/
-
-
-How it works
-============
-
-Using the recommended default configuration, the URL
-``/accounts/register/`` will map to the view
-``registration.views.register``, which displays a registration form
-(an instance of ``registration.forms.RegistrationForm``); this form
-asks for a username, email address and password, and verifies that the
-username is available and requires the password to be entered twice
-(to catch typos). It then does three things:
-
-1. Creates an instance of ``django.contrib.models.auth.User``, using
-   the supplied username, email address and password; the
-   ``is_active`` field on the new ``User`` will be set to ``False``,
-   meaning that the account is inactive and the user will not be able
-   to log in yet.
-
-2. Creates an instance of ``registration.models.RegistrationProfile``,
-   stores an activation key (a SHA1 hash generated from the new user's
-   username plus a randomly-generated "salt"), and relates that
-   ``RegistrationProfile`` to the ``User`` it just created.
-
-3. Sends an email to the user (at the address they supplied)
-   containing a link which can be clicked to activate the account.
-
-For details on customizing this process, including use of alternate
-registration form classes and automatic creation of a site-specific
-profile, see the sections on customization below.
-
-After the activation email has been sent,
-``registration.views.register`` issues a redirect to the URL
-``/accounts/register/complete/``. By default, this is mapped to the
-``direct_to_template`` generic view, and displays the template
-``registration/registration_complete.html``; this is intended to show
-a short message telling the user to check his/her email for the
-activation link.
-
-The activation link will map to the view
-``registration.views.activate``, which will attempt to activate the
-account by setting the ``is_active`` field on the ``User`` to
-``True``. If the activation key for the ``User`` has expired (this is
-controlled by the setting ``ACCOUNT_ACTIVATION_DAYS``, as described
-above), the account will not be activated (see the section on
-maintenance below for instructions on cleaning out expired accounts
-which have not been activated).
-
-
-Maintenance
-===========
-
-Inevitably, a site which uses a two-step process for user signup --
-registration followed by activation -- will accumulate a certain
-number of accounts which were registered but never activated. These
-accounts clutter up the database and tie up usernames which might
-otherwise be actively used, so it's desirable to clean them out
-periodically. For this purpose, a script,
-``registration/bin/deleted_expired_users.py``, is provided, which is
-suitable for use as a regular cron job. See that file for notes on how
-to add it to your crontab, and the included models documentation (see
-below) for discussion of how it works and some caveats.
-
-
-Where to go from here
-=====================
-
-Full documentation for all included components is bundled in the
-packaged release; see the following files for details:
-
-* `Forms documentation`_ for details on ``RegistrationForm``,
-  pre-packaged subclasses and available customizations.
-
-* `Models documentation`_ for details on ``RegistrationProfile`` and
-  its custom manager.
-
-* `Views documentation`_ for details on the ``register`` and
-  ``activate`` views, and methods for customizing them.
-
-.. _Forms documentation: forms.txt
-.. _Models documentation: models.txt
-.. _Views documentation: views.txt
-
-
-Development
-===========
-
-The `latest released version`_ of this application is 0.7, and is
-quite stable; it's already been deployed on a number of sites,
-including djangoproject.com. You can also obtain the absolute freshest
-code from `the development repository_`, but be warned that the
-development code may not always be backwards-compatible, and may well
-contain bugs that haven't yet been fixed.
-
-This document covers the 0.7 release of django-registration; new
-features introduced in the development trunk will be added to the
-documentation at the time of the next packaged release.
-
-.. _latest released version: http://pypi.python.org/pypi/django-registration/0.7
-.. _the development repository: http://www.bitbucket.org/ubernostrum/django-registration/src/
-
-
-Changes from previous versions
-==============================
-
-Several new features were added between version 0.2 and version 0.3;
-for details, see the CHANGELOG.txt file distributed with the packaged
-0.3 release.
-
-One important change to note before upgrading an installation of
-version 0.1 is a change to the ``RegistrationProfile`` model; the
-field ``key_generated`` has been removed, since it was redundant with
-the field ``date_joined`` on Django's bundled ``User`` model. Since
-this field became a ``NOT NULL`` column in the database, you will need
-to either drop the ``NOT NULL`` constraint or, preferably, simply drop
-the column. Consult your database's documentation for the correct way
-to handle this.
-
-Between version 0.3 and version 0.4, validation of the password fields
-was moved from ``clean_password2()`` to ``clean_password()``; this
-means that errors from mismatched passwords will now show up in
-``non_field_errors()`` instead of ``errors["password2"]``.
-
-Between version 0.6 and version 0.7, the script
-``registration/bin/delete_expired_users.py`` was removed, and replaced
-with a custom management command; you can now simply run ``manage.py
-cleanupregistration`` from any project which has django-registration
-installed.
-
-
-Dependencies
-============
-
-The only dependencies for this application are a functioning install
-of Django 1.0 or newer and, of course, a Django project in which you'd
-like to use it.
-
-Your Django project should have ``django.contrib.admin``,
-``django.contrib.auth`` and ``django.contrib.sites`` in its
-``INSTALLED_APPS`` setting.
-
-
-What this application does not do
-=================================
-
-This application does not integrate in any way with OpenID, nor should
-it; one of the key selling points of OpenID is that users **don't**
-have to walk through an explicit registration step for every site or
-service they want to use :)
-
-
-If you spot a bug
-=================
-
-Head over to this application's `project page on Bitbucket`_ and
-check `the issues list`_ to see if it's already been reported. If not,
-open a new issue and I'll do my best to respond quickly.
-
-.. _project page on Bitbucket: http://www.bitbucket.org/ubernostrum/django-registration/overview/
-.. _the issues list: http://www.bitbucket.org/ubernostrum/django-registration/issues/

docs/views.txt

-=====
-Views
-=====
-
-
-Two views are included which, between them, handle the process of
-first registering and then activating new user accounts; both views
-are found in ``registration.views``.
-
-
-``activate``
-============
-
-Activate a ``User``'s account from an activation key, if their key is
-valid and hasn't expired.
-
-By default, use the template ``registration/activate.html``; to
-change this, pass the name of a template as the keyword argument
-``template_name``.
-
-**Required arguments**
-
-``activation_key``
-    The activation key to validate and use for activating the
-    ``User``.
-    
-**Optional arguments**
-
-``extra_context``
-    A dictionary of variables to add to the template context. Any
-    callable object in this dictionary will be called to produce the
-    end result which appears in the context.
-
-``template_name``
-    A custom template to use.
-
-**Context:**
-
-``account``
-    The ``User`` object corresponding to the account, if the
-    activation was successful. ``False`` if the activation was not
-    successful.
-    
-``expiration_days``
-    The number of days for which activation keys stay valid after
-    registration.
-
-Any extra variables supplied in the ``extra_context`` argument (see
-above).
-
-**Template:**
-    
-registration/activate.html or ``template_name`` keyword argument.
-
-
-``register``
-============
-
-Allow a new user to register an account.
-    
-Following successful registration, issue a redirect; by default, this
-will be whatever URL corresponds to the named URL pattern
-``registration_complete``, which will be
-``/accounts/register/complete/`` if using the included URLConf. To
-change this, point that named pattern at another URL, or pass your
-preferred URL as the keyword argument ``success_url``.
-    
-By default, ``registration.forms.RegistrationForm`` will be used as
-the registration form; to change this, pass a different form class as
-the ``form_class`` keyword argument. The form class you specify must
-have a method ``save`` which will create and return the new ``User``.
-
-By default, use the template ``registration/registration_form.html``;
-to change this, pass the name of a template as the keyword argument
-``template_name``.
-
-**Required arguments**
-
-None.
-
-**Optional arguments**
-
-``form_class``
-    The form class to use for registration.
-
-``extra_context``
-    A dictionary of variables to add to the template context. Any
-    callable object in this dictionary will be called to produce the
-    end result which appears in the context.
-
-``success_url``
-    The URL to redirect to on successful registration.
-
-``template_name``
-    A custom template to use.
-
-**Context:**
-
-``form``
-    The registration form.
-    
-Any extra variables supplied in the ``extra_context`` argument (see
-above).
-
-**Template:**
-
-registration/registration_form.html or ``template_name`` keyword
-argument.
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.