diff --git a/README.md b/README.md
index 6189934..43bf0bf 100644
--- a/README.md
+++ b/README.md
@@ -1,209 +1,8 @@
-# Django Social Registration
+# django-socialregistration
-Django Social Registration enables developers to add alternative registration
-methods based on third party sites.
-
-Supported methods currently are:
-
-* OpenID
-* OAuth
-* Facebook Connect
-
-## Requirements
-
-* [Django](http://pypi.python.org/pypi/django/)
-* [oauth2](http://pypi.python.org/pypi/oauth2/)
-* [python-openid](http://pypi.python.org/pypi/python-openid)
-* [python-sdk](https://github.com/facebook/python-sdk)
-
-## Installation
-
- pip install django-socialregistration
- pip install -e git+https://github.com/facebook/python-sdk.git#egg=FacebookSDK
-
-## Configuration
-
-1. Add `socialregistration` to your `INSTALLED_APPS`
-2. Add `django.core.context_processors.request` to the [TEMPLATE_CONTEXT_PROCESSORS](http://docs.djangoproject.com/en/1.3/ref/settings/#template-context-processors)
-3. Include `socialregistration.urls` in your top level urls:
-
- urlpatterns = patterns('',
- # ...
- url(r'^social/', include('socialregistration.urls')))
-
-4. Make sure you are using a [RequestContext](http://docs.djangoproject.com/en/1.3/ref/templates/api/#subclassing-context-requestcontext) wherever you are planning to display the
- login buttons
-
- from django.template import RequestContext
-
- def login(request):
- # ...
- return render_to_response('login.html',
- {}, context_instance = RequestContext(request))
-
-5. Once you're done, and configured, etc, don't forget to `python manage.py syncdb` your project.
-
-## Facebook Connect
-
-#### Configuration
-
-1. Add the Facebook API keys to the your settings, variable names are
-
- FACEBOOK_APP_ID = ''
- FACEBOOK_API_KEY = ''
- FACEBOOK_SECRET_KEY = ''
-
-2. Add `socialregistration.auth.FacebookAuth` to [AUTHENTICATION_BACKENDS](http://docs.djangoproject.com/en/1.3/ref/settings/#authentication-backends)
-3. Add `socialregistration.middleware.FacebookMiddleware` to [MIDDLEWARE_CLASSES](http://docs.djangoproject.com/en/1.3/ref/settings/#middleware-classes)
-4. (Optional) Add `FACEBOOK_REQUEST_PERMISSIONS` to your settings. This is a comma seperated list of the permissions you need. e.g:
-
- FACEBOOK_REQUEST_PERMISSIONS = 'email,user_about_me'
-
-
-
-#### Usage
-
-* Add tags to your template file
-
- {% load facebook_tags %}
- {% facebook_button %}
- {% facebook_js %}
-
- You can also specify your own custom button image by appending it to the `facebook_button` template tag:
-
- {% facebook_button 'http://example.com/other_facebook_button.png' %}
-
- You want to keep the `{% facebook_js %}` as far down in your HTML structure as possible to
- not impact the load time of the page.
-
- Also make sure you followed the steps to include a `RequestContext` in your template that
- is using these tags.
-
-## Twitter
-
-#### Configuration
-
-1. Add the Twitter API keys and endpoints to your settings, variable names are
-
- TWITTER_CONSUMER_KEY = ''
- TWITTER_CONSUMER_SECRET_KEY = ''
- TWITTER_REQUEST_TOKEN_URL = ''
- TWITTER_ACCESS_TOKEN_URL = ''
- TWITTER_AUTHORIZATION_URL = ''
-
-2. Add `socialregistration.auth.TwitterAuth` to `AUTHENTICATION_BACKENDS`
-3. Add the right callback URL to your Twitter account
-
-#### Usage
-
-* Add tags to your template file
-
- {% load twitter_tags %}
- {% twitter_button %}
-
- Same note here. Make sure you're serving the page with a `RequestContext`
-
- You can also specify your own custom button image by appending it to the `twitter_button` template tag:
-
- {% twitter_button 'http://example.com/other_twitter_button.png' %}
-
-
-## LinkedIn
-
-#### Configuration
-
-1. Add the LinkedIn API keys and endpoints to your settings, variable names are
-
- LINKEDIN_CONSUMER_KEY = ''
- LINKEDIN_CONSUMER_SECRET_KEY = ''
- LINKEDIN_REQUEST_TOKEN_URL = ''
- LINKEDIN_ACCESS_TOKEN_URL = ''
- LINKEDIN_AUTHORIZATION_URL = ''
-
-2. Add `socialregistration.auth.LinkedInAuth` to `AUTHENTICATION_BACKENDS`
-3. Add the right callback URL to your LinkedIn account
-
-#### Usage
-
-* Add tags to your template file
-
- {% load linkedin_tags %}
- {% linkedin_button %}
-
- Same note here. Make sure you're serving the page with a `RequestContext`
-
- You can also specify your own custom button image by appending it to the `linkedin_button` template tag:
-
- {% linkedin_button 'http://example.com/other_linkedin_button.png' %}
-
-
-## OAuth
-
-Check out how the Twitter authentication works. Basically it's just plugging
-together some urls and creating an auth backend, a model and a view.
-
-## OpenID
-
-#### Configuration
-
-* Add `socialregistration.auth.OpenIDAuth` to `AUTHENTICATION_BACKENDS`
-
-#### Usage
-
-* Add tags to your template file
-
- {% load openid_tags %}
- {% openid_form %}
-
-## Logging users out
-
-You can use the standard `{% url auth_logout %}`. Alternatively there is also `{% url social_logout %}`
-which is basically a wrapper around `auth_logout`.
-
-*This will log users only out of your site*.
-
-To make sure they're logged out of other sites too, use something like this:
-
- Logout
-
-Or redirect them to the provider they logged in from.
-
-## Additional Settings
-
- SOCIALREGISTRATION_USE_HTTP = False
- SOCIALREGISTRATION_GENERATE_USERNAME = False
-
-Set either `True` if you want to enable HTTPS or have the users skip the username form.
-
-
-## Signals
-
-The app provides two signals that fire when users connect their accounts and log in:
-
- socialregistration.signals.connect
- socialregistration.signals.login
-
-The signal handlers needs to accept three arguments, and can listen on specific profiles:
-
- from socialregistration import signals
- from socialregistration import models
-
- def connect_facebook(user, profile, client, **kwargs):
- # Do fancy stuff like fetching more user info with the client
- pass
-
- def login_facebook(user, profile, client, **kwargs):
- # Do fancy stuff like finding logged in friends
- pass
-
- signals.connect.connect(connect_facebook, sender = models.FacebookProfile)
- signals.login.connect(login_facebook, sender = models.FacebookProfile)
-
-This works too with OpenID and OAuth profiles.
-
-# Release Notes
-
-### *v0.4.6*
-* Added LinkedIn support
-* Bugfixes and OAuth2 beginnings for Facebook
+django-socialregistratin enables developers to add user registration
+with OAuth, OAuth2 and OpenID services.
+See
+[documentation](http://django-socialregistration.readthedocs.org/en/latest/)
+for installation and configuration.
diff --git a/README.rst b/README.rst
index 4710f1e..810ad18 100644
--- a/README.rst
+++ b/README.rst
@@ -1,166 +1,8 @@
-Django Social Registration
-Django Social Registration enables developers to add alternative registration methods based on third party sites.
-Supported methods currently are:
-
-- OpenID
-- OAuth
-- Facebook Connect
-
-Requirements
-
-Installation
- pip install django-socialregistration
- pip install -e git+https://github.com/facebook/python-sdk.git#egg=FacebookSDK
-
-Configuration
-
-- Add
socialregistration to your INSTALLED_APPS
-- Add
django.core.context_processors.request to the TEMPLATE_CONTEXT_PROCESSORS
-Include socialregistration.urls in your top level urls:
-urlpatterns = patterns('',
- # ...
- url(r'^social/', include('socialregistration.urls')))
-
Make sure you are using a RequestContext wherever you are planning to display the login buttons
-from django.template import RequestContext
+django-socialregistration
+=========================
-def login(request):
- # ...
- return render_to_response('login.html',
- {}, context_instance = RequestContext(request))
-
Once you're done, and configured, etc, don't forget to python manage.py syncdb your project.
-Facebook Connect
-Configuration
-
-Add the Facebook API keys to the your settings, variable names are
-FACEBOOK_APP_ID = ''
-FACEBOOK_API_KEY = ''
-FACEBOOK_SECRET_KEY = ''
-
- Add
socialregistration.auth.FacebookAuth to AUTHENTICATION_BACKENDS
-- Add
socialregistration.middleware.FacebookMiddleware to MIDDLEWARE_CLASSES
-(Optional) Add FACEBOOK_REQUEST_PERMISSIONS to your settings. This is a comma seperated list of the permissions you need. e.g:
-FACEBOOK_REQUEST_PERMISSIONS = 'email,user_about_me'
-
-Usage
-
-You can also specify your own custom button image by appending it to the facebook_button template tag:
- {% facebook_button 'http://example.com/other_facebook_button.png' %}
-
-You want to keep the {% facebook_js %} as far down in your HTML structure as possible to not impact the load time of the page.
-Also make sure you followed the steps to include a RequestContext in your template that is using these tags.
-
-Configuration
-
-Add the Twitter API keys and endpoints to your settings, variable names are
-TWITTER_CONSUMER_KEY = ''
-TWITTER_CONSUMER_SECRET_KEY = ''
-TWITTER_REQUEST_TOKEN_URL = ''
-TWITTER_ACCESS_TOKEN_URL = ''
-TWITTER_AUTHORIZATION_URL = ''
-
- Add
socialregistration.auth.TwitterAuth to AUTHENTICATION_BACKENDS
-Add the right callback URL to your Twitter account
-Usage
-
-Same note here. Make sure you're serving the page with a RequestContext
-You can also specify your own custom button image by appending it to the twitter_button template tag:
- {% twitter_button 'http://example.com/other_twitter_button.png' %}
-
-LinkedIn
-Configuration
-
-Add the LinkedIn API keys and endpoints to your settings, variable names are
- LINKEDIN_CONSUMER_KEY = ''
-LINKEDIN_CONSUMER_SECRET_KEY = ''
-LINKEDIN_REQUEST_TOKEN_URL = ''
-LINKEDIN_ACCESS_TOKEN_URL = ''
-LINKEDIN_AUTHORIZATION_URL = ''
-
- Add
socialregistration.auth.LinkedInAuth to AUTHENTICATION_BACKENDS
-Add the right callback URL to your LinkedIn account
-Usage
-
-Same note here. Make sure you're serving the page with a RequestContext
-You can also specify your own custom button image by appending it to the linkedin_button template tag:
- {% linkedin_button 'http://example.com/other_linkedin_button.png' %}
-
-OAuth
-Check out how the Twitter authentication works. Basically it's just plugging together some urls and creating an auth backend, a model and a view.
-OpenID
-Configuration
-
-- Add
socialregistration.auth.OpenIDAuth to AUTHENTICATION_BACKENDS
-
-Usage
-
-Logging users out
-You can use the standard {% url auth_logout %}. Alternatively there is also {% url social_logout %} which is basically a wrapper around auth_logout.
-This will log users only out of your site.
-To make sure they're logged out of other sites too, use something like this:
- <a href="#" onclick:"javascript:FB.logout(function(resp){ document.location = '{% url social_logout %}'; })">Logout</a>
-
-Or redirect them to the provider they logged in from.
-Additional Settings
- SOCIALREGISTRATION_USE_HTTP = False
- SOCIALREGISTRATION_GENERATE_USERNAME = False
-
-Set either True if you want to enable HTTPS or have the users skip the username form.
-Signals
-The app provides two signals that fire when users connect their accounts and log in:
- socialregistration.signals.connect
- socialregistration.signals.login
-
-The signal handlers needs to accept three arguments, and can listen on specific profiles:
- from socialregistration import signals
- from socialregistration import models
+django-socialregistratin enables developers to add user registration
+with OAuth, OAuth2 and OpenID services.
- def connect_facebook(user, profile, client, **kwargs):
- # Do fancy stuff like fetching more user info with the client
- pass
-
- def login_facebook(user, profile, client, **kwargs):
- # Do fancy stuff like finding logged in friends
- pass
-
- signals.connect.connect(connect_facebook, sender = models.FacebookProfile)
- signals.login.connect(login_facebook, sender = models.FacebookProfile)
-
-This works too with OpenID and OAuth profiles.
-Release Notes
-v0.4.6
-
-- Added LinkedIn support
-- Bugfixes and OAuth2 beginnings for Facebook
-
+See `documentation `_
+for installation and configuration.
diff --git a/docs/contrib/facebook.rst b/docs/contrib/facebook.rst
new file mode 100644
index 0000000..207e402
--- /dev/null
+++ b/docs/contrib/facebook.rst
@@ -0,0 +1,33 @@
+Facebook
+========
+
+- Add ``socialregistration.contrib.facebook`` to your ``INSTALLED_APPS``
+
+::
+
+ INSTALLED_APPS = (
+ 'socialregistration',
+ 'socialregistration.contrib.facebook'
+ )
+
+- Add your API keys and (comma seperated) permissions you request:
+
+::
+
+ FACEBOOK_APP_ID = ''
+ FACEBOOK_SECRET_KEY = ''
+ FOURSQUARE_REQUEST_PERMISSIONS = ''
+
+- Anywhere in your templates:
+
+::
+
+ {% load facebook %}
+ {% facebook_button %}
+
+Or:
+
+::
+
+ {% load facebook %}
+ {% facebook_button 'custom/button/image.png' %}
diff --git a/docs/contrib/foursquare.rst b/docs/contrib/foursquare.rst
new file mode 100644
index 0000000..6600d0b
--- /dev/null
+++ b/docs/contrib/foursquare.rst
@@ -0,0 +1,34 @@
+Foursquare
+==========
+
+- Add ``socialregistration.contrib.foursquare`` to your ``INSTALLED_APPS``
+
+::
+
+ INSTALLED_APPS = (
+ 'socialregistration',
+ 'socialregistration.contrib.foursquare'
+ )
+
+- Add your API keys and (comma seperated) permissions you request:
+
+::
+
+ FOURSQUARE_CLIENT_ID = ''
+ FOURSQUARE_CLIENT_SECRET = ''
+ FOURSQUARE_REQUEST_PERMISSIONS = ''
+
+
+- Anywhere in your templates:
+
+::
+
+ {% load foursquare %}
+ {% foursquare_button %}
+
+Or:
+
+::
+
+ {% load foursquare %}
+ {% foursquare_button 'custom/button/image.png' %}
diff --git a/docs/contrib/github.rst b/docs/contrib/github.rst
new file mode 100644
index 0000000..9ca1f1c
--- /dev/null
+++ b/docs/contrib/github.rst
@@ -0,0 +1,33 @@
+Github
+=======
+
+- Add ``socialregistration.contrib.github`` to your ``INSTALLED_APPS``
+
+::
+
+ INSTALLED_APPS = (
+ 'socialregistration',
+ 'socialregistration.contrib.github'
+ )
+
+- Add your API keys and (comma seperated) permissions you request:
+
+::
+
+ GITHUB_CLIENT_ID = ''
+ GITHUB_CLIENT_SECRET = ''
+ GITHUB_REQUEST_PERMISSIONS = ''
+
+- Anywhere in your templates:
+
+::
+
+ {% load github %}
+ {% github_button %}
+
+Or:
+
+::
+
+ {% load github %}
+ {% github_button 'custom/button/image.png' %}
diff --git a/docs/contrib/linkedin.rst b/docs/contrib/linkedin.rst
new file mode 100644
index 0000000..9ffb114
--- /dev/null
+++ b/docs/contrib/linkedin.rst
@@ -0,0 +1,33 @@
+LinkedIn
+========
+
+- Add ``socialregistration.contrib.linkedin`` to your ``INSTALLED_APPS``
+
+::
+
+ INSTALLED_APPS = (
+ 'socialregistration',
+ 'socialregistration.contrib.linkedin'
+ )
+
+- Add your API keys:
+
+::
+
+ LINKEDIN_CONSUMER_KEY = ''
+ LINKEDIN_CONSUMER_SECRET_KEY = ''
+
+
+- Anywhere in your templates:
+
+::
+
+ {% load linkedin %}
+ {% linkedin_button %}
+
+Or:
+
+::
+
+ {% load linkedin %}
+ {% linkedin_button 'custom/button/image.png' %}
diff --git a/docs/contrib/openid.rst b/docs/contrib/openid.rst
new file mode 100644
index 0000000..0cd113c
--- /dev/null
+++ b/docs/contrib/openid.rst
@@ -0,0 +1,25 @@
+OpenID
+======
+
+- Add ``socialregistration.contrib.openid`` to your ``INSTALLED_APPS``
+
+::
+
+ INSTALLED_APPS = (
+ 'socialregistration',
+ 'socialregistration.contrib.openid'
+ )
+
+- Anywhere in your templates:
+
+::
+
+ {% load openid %}
+ {% openid_form %}
+
+Or
+
+::
+
+ {% load openid %}
+ {% openid_form 'https://www.google.com/accounts/o8/id' 'login/with/google.png' %}
diff --git a/docs/contrib/tumblr.rst b/docs/contrib/tumblr.rst
new file mode 100644
index 0000000..10b9a51
--- /dev/null
+++ b/docs/contrib/tumblr.rst
@@ -0,0 +1,33 @@
+Tumblr
+======
+
+- Add ``socialregistration.contrib.tumblr`` to your ``INSTALLED_APPS``
+
+::
+
+ INSTALLED_APPS = (
+ 'socialregistration',
+ 'socialregistration.contrib.tumblr'
+ )
+
+- Add your API keys:
+
+::
+
+ TUMBLR_CONSUMER_KEY = ''
+ TUMBLR_CONSUMER_SECRET_KEY = ''
+
+
+- Anywhere in your templates:
+
+::
+
+ {% load tumblr %}
+ {% tumblr_button %}
+
+Or:
+
+::
+
+ {% load tumblr %}
+ {% tumblr_button 'custom/button/image.png' %}
diff --git a/docs/contrib/twitter.rst b/docs/contrib/twitter.rst
new file mode 100644
index 0000000..4e7127f
--- /dev/null
+++ b/docs/contrib/twitter.rst
@@ -0,0 +1,33 @@
+Twitter
+=======
+
+- Add ``socialregistration.contrib.twitter`` to your ``INSTALLED_APPS``
+
+::
+
+ INSTALLED_APPS = (
+ 'socialregistration',
+ 'socialregistration.contrib.twitter'
+ )
+
+- Add your API keys:
+
+::
+
+ TWITTER_CONSUMER_KEY = ''
+ TWITTER_CONSUMER_SECRET_KEY = ''
+
+
+- Anywhere in your templates:
+
+::
+
+ {% load twitter %}
+ {% twitter_button %}
+
+Or:
+
+::
+
+ {% load twitter %}
+ {% twitter_button 'custom/button/image.png' %}
diff --git a/docs/index.rst b/docs/index.rst
index c61305c..5d81408 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,16 +1,14 @@
-.. django-socialregistration documentation master file, created by
- sphinx-quickstart on Tue Oct 4 12:05:14 2011.
- You can adapt this file completely to your liking, but it should at least
- contain the root `toctree` directive.
+.. include:: ../README.rst
-Welcome to django-socialregistration's documentation!
-=====================================================
-
-Contents:
.. toctree::
:maxdepth: 2
+ installation.rst
+ services.rst
+ settings.rst
+
+
Indices and tables
==================
diff --git a/docs/installation.rst b/docs/installation.rst
new file mode 100644
index 0000000..deb3506
--- /dev/null
+++ b/docs/installation.rst
@@ -0,0 +1,42 @@
+Setup
+-----
+
+Requirements
+============
+
+- `oauth2 `_
+- `python-openid `_
+- `facebook-python-sdk `_
+
+Installation
+============
+
+::
+
+ pip install django-socialregistration
+ pip install -e git+https://github.com/facebook/python-sdk.git#egg=FacebookSDK
+
+
+Configuration
+=============
+
+The most basic configuration is to add ``socialregistration`` to your ``INSTALLED_APPS``
+
+::
+
+ INSTALLED_APPS = (
+ 'socialregistration'
+ )
+
+
+Include ``socialregistration.urls`` into your root ``urls.py`` file
+
+::
+
+ urlpatterns = patterns('',
+ url(r'^social/', include('socialregistration.urls',
+ namespace = 'socialregistration')))
+
+.. note::
+
+ The ``namespace = 'socialregistration'`` argument is required.
diff --git a/docs/services.rst b/docs/services.rst
new file mode 100644
index 0000000..b5ddf1f
--- /dev/null
+++ b/docs/services.rst
@@ -0,0 +1,10 @@
+Services
+--------
+
+.. include:: contrib/openid.rst
+.. include:: contrib/facebook.rst
+.. include:: contrib/twitter.rst
+.. include:: contrib/github.rst
+.. include:: contrib/linkedin.rst
+.. include:: contrib/foursquare.rst
+.. include:: contrib/tumblr.rst
diff --git a/docs/settings.rst b/docs/settings.rst
new file mode 100644
index 0000000..2186ace
--- /dev/null
+++ b/docs/settings.rst
@@ -0,0 +1,61 @@
+Settings
+--------
+
+.. currentmodule:: socialregistration.conf.settings
+
+.. attribute:: USE_HTTPS
+
+ :Default: ``False``
+
+ Whether your callback URLs are served via SSL.
+
+
+.. attribute:: SOCIALREGISTRATION_SESSION_KEY
+
+ :Default: ``'socialregistration:'``
+
+ The session key prefix to store temporary user information with while the
+ user is setting up an account.
+
+
+.. attribute:: SOCIALREGISTRATION_GENERATE_USERNAME
+
+ :Default: ``False``
+
+ If set to ``True`` the username will be generated automatically
+
+
+.. attribute:: SOCIALREGISTRATION_GENERATE_USERNAME_FUNCTION
+
+ :Default: ``'socialregistration.utils.generate_username'``
+
+ If ``SOCIALREGISTRATION_GENERATE_USERNAME`` is ``True``, this function will
+ be called and should return a username. The function will receive three
+ arguments:
+
+ - A user model
+ - A profile model
+ - An API client
+
+
+.. attribute:: SOCIALREGISTRATION_SETUP_FORM
+
+ :Default: ``'socialregistration.forms.UserForm'``
+
+ IF ``SOCIALREGISTRATION_GENERATE_USERNAME`` is ``False``, this form will be
+ used to capture data from the user, such as username and email address.
+
+
+.. attribute:: SOCIALREGISTRATION_INITIAL_DATA_FUNCTION
+
+ :Default: ``None``
+
+ A function that should return some initial data for the
+ ``SOCIALREGISTRATION_SETUP_FORM``. The function takes four parameters:
+
+ - The request object
+ - A user model
+ - A profile model
+ - An API client
+
+