Added more descriptive documentation for OAuth. #643

Merged
merged 1 commit into from Mar 22, 2013
@@ -16,16 +16,38 @@ backend name as prefix::
<uppercase backend name>_EXTRA_DATA
-Example::
-
- FACEBOOK_EXTRA_DATA = [(..., ...)]
-
-Settings must be a list of tuples mapping value name in response and value
-alias used to store. A third value (boolean) is supported, its purpose is
-to signal if the value should be discarded if it evaluates to ``False``, this
-is to avoid replacing old (needed) values when they don't form part of current
-response. If not present, then this check is avoided and the value will replace
-any data.
+For example, a subset of the data GitHub's provider returns is::
+
+ {
+ 'avatar_url': 'https://secure.gravatar.com/avatar/[...]',
+ 'created_at': '2009-02-11T02:18:24Z',
+ 'email': 'john@example.com',
+ 'id': 53537,
+ 'login': 'github_user'
+ 'name': 'Johnny Codemore',
+ [...]
+ }
+
+To add the avatar and login items to ``UserSocialAuth.extra_data``, you would
+define the following in ``settings.py``::
+
+ GITHUB_EXTRA_DATA = [
+ ('avatar_url', 'avatar'),
+ ('login', 'login'),
+ ]
+
+Settings must be a list of tuples mapping value name in response and value's
+alias used in ``UserSocialAuth.extra_data``. The alias is used to normalize
+data access across multiple backends. In the example above, GitHub sends
+back a URL for the avatar in the field ``avatar_url``. Alternatively, another
+backend can send it as ``avatar``, or ``gravatar``. By using a single name,
+``avatar``, within ``UserSocialAuth.extra_data`` your application can more
+easily use this information.
+
+A third value (boolean) is supported, its purpose is to signal if the value
+should be discarded if it evaluates to ``False``, this is to avoid replacing
+old (needed) values when they don't form part of current response. If not
+present, then this check is avoided and the value will replace any data.
.. _OAuth: http://oauth.net/