Merge afdf232 into db135dd

CONTRIBUTING.md

@@ -170,3 +170,10 @@ translations better than dealing them through the pull request system.
 Head over to [django-user-accounts on Transifex](https://www.transifex.com/projects/p/django-user-accounts/)
 and find the language you would like to contribute. If you do not find your
 language then please submit an issue and we will get it setup.
+
+## Documentation
+
+We use [Mkdocs](http://www.mkdocs.org/) to build documentation and welcome contributions.
+To get started, first run `pip install -r docs-requirements` and then `mkdocs serve`, then visit
+the existing documentation in your brower at http://0.0.0.0:8000.
+Please view your changes to the documentation by 

docs-requirements.txt

@@ -0,0 +1 @@
+mkdocs

docs/changelog.md

@@ -0,0 +1,8 @@
+CHANGELOG
+=========
+
+1.0
+---
+
+-   initial release
+-   if migrating from Pinax; see [Migration from Pinax](migration.md)

docs/faq.md

@@ -0,0 +1,66 @@
+FAQ
+===
+
+This document is a collection of frequently asked questions about
+django-user-accounts.
+
+What is the difference between django-user-accounts and django.contrib.auth?
+----------------------------------------------------------------------------
+
+django-user-accounts is designed to supplement `django.contrib.auth`.
+This app provides improved views for log in, password reset, log out and
+adds sign up functionality. We try not to duplicate code when Django
+provides a good implementation. For example, we did not re-implement
+password reset, but simply provide an improved view which calls into the
+secure Django password reset code. `django.contrib.auth` is still
+providing many of supporting elements such as `User` model, default
+authentication backends, helper functions and authorization.
+
+django-user-accounts takes your Django project from having simple log
+in, log out and password reset to a full blown account management system
+that you will end up building anyways.
+
+Why can email addresses get out of sync?
+----------------------------------------
+
+django-user-accounts stores email addresses in two locations. The
+default `User` model contains an `email` field and django-user-accounts
+provides an `EmailAddress` model. This latter is provided to support
+multiple email addresses per user.
+
+If you use a custom user model you can prevent the double storage. This
+is because you can choose not to do any email address storage.
+
+If you don’t use a custom user model then make sure you take extra
+precaution. When editing email addresses either in the shell or admin
+make sure you update in both places. Only the primary email address is
+stored on the `User` model.
+
+Why does auto-login after sign up not log my user in?
+-----------------------------------------------------
+
+If you are using Django 1.6+ and
+`django.contrib.auth.backends.ModelBackend` does not exist in your
+`AUTHENTICATION_BACKENDS` then you will experience an issue where users
+are not logged in after sign up (when
+`ACCOUNT_EMAIL_CONFIRMATION_REQUIRED` is `False`.)
+
+This has been fixed, but the default behavior is buggy (for this use
+case) to maintain backward compatibility. In a future version of
+django-user-accounts the default behavior will not be buggy.
+
+To fix, simply set:
+
+    ACCOUNT_USE_AUTH_AUTHENTICATE = True
+
+in your Django settings. This will cause the `login_user` method of
+`SignupView` to use proper backend authentication to determine the
+correct authentication backend for the user. You will need to make sure
+that `SignupView.identifier_field` is set to represent the correct field
+on the sign up form to use as the username for credentials. By default
+the `username` field is used (to be consistent with the default username
+authentication used for log in.)
+
+If you have a custom need for user credentials passed to the
+authentication backends, you may override the behavior using the hookset
+`get_user_credentials`.

docs/installation.md

@@ -0,0 +1,73 @@
+Installation
+============
+
+Install the development version:
+
+    pip install django-user-accounts
+
+Add `account` to your `INSTALLED_APPS` setting:
+
+    INSTALLED_APPS = (
+        # ...
+        "account",
+        # ...
+    )
+
+See the list of [settings](settings.md) to modify the default behavior of
+django-user-accounts and make adjustments for your website.
+
+Add `account.urls` to your URLs definition:
+
+    urlpatterns = patterns("",
+        ...
+        url(r"^account/", include("account.urls")),
+        ...
+    )
+
+Add `account.context_processors.account` to
+`TEMPLATE_CONTEXT_PROCESSORS`:
+
+    TEMPLATE_CONTEXT_PROCESSORS = [
+        ...
+        "account.context_processors.account",
+        ...
+    ]
+
+Add `account.middleware.LocaleMiddleware` and
+`account.middleware.TimezoneMiddleware` to `MIDDLEWARE_CLASSES`:
+
+    MIDDLEWARE_CLASSES = [
+        ...
+        "account.middleware.LocaleMiddleware",
+        "account.middleware.TimezoneMiddleware",
+        ...
+    ]
+
+Once everything is in place make sure you run `syncdb` (Django 1.4 and
+1.6) or `migrate` (Django 1.7) to modify the database with the `account`
+app models.
+
+Dependencies
+------------
+
+### `django.contrib.auth`
+
+This is bundled with Django. It is enabled by default with all new
+Django projects, but if you adding django-user-accounts to an existing
+project you need to make sure `django.contrib.auth` is installed.
+
+### `django.contrib.sites`
+
+This is bundled with Django. It is enabled by default with all new
+Django projects. It is used to provide links back to the site in emails
+or various places in templates that need an absolute URL.
+
+### [django-appconf](https://github.com/jezdez/django-appconf)
+
+We use django-appconf for app settings. It is listed in
+`install_requires` and will be installed when pip installs.
+
+### [pytz](http://pypi.python.org/pypi/pytz/)
+
+pytz is used for handling timezones for accounts. This dependency is
+critical due to its extensive dataset for timezones.