From d9c8dee453a1e751a281a6b99bcfac3c8dc41a60 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Mat=C3=ADas=20Aguirre?= Date: Thu, 2 Jun 2011 14:04:37 -0300 Subject: [PATCH] Docs small improvements --- README.rst | 119 ++++++++++++++++++-------------------- doc/backends/facebook.rst | 16 ++--- doc/backends/google.rst | 31 +++++----- doc/backends/oauth.rst | 4 +- doc/backends/openid.rst | 4 +- doc/backends/twitter.rst | 6 +- doc/configuration.rst | 25 ++++---- doc/demo.rst | 2 +- doc/installing.rst | 4 +- doc/signals.rst | 12 ++-- doc/testing.rst | 6 +- 11 files changed, 109 insertions(+), 120 deletions(-) diff --git a/README.rst b/README.rst index 8c1dbee..cf26886 100644 --- a/README.rst +++ b/README.rst @@ -14,7 +14,7 @@ third parties. Demo ----- There's a demo at http://social.matiasaguirre.net/. -Note: It lacks Orkut support at the moment. +Note: It lacks some backends support at the moment. -------- @@ -52,14 +52,14 @@ credentials, some features are: ------------ Dependencies ------------ -Dependencies that *must* be meet to use the application: +Dependencies that **must** be meet to use the application: - OpenId_ support depends on python-openid_ - OAuth_ support depends on python-oauth2_ -- Twitter and Facebook support demands an application registration - on their corresponding sites. +- Several backends demands application registration on their corresponding + sites. ------------ @@ -91,7 +91,7 @@ or:: ------------- Configuration ------------- -- Add social_auth to PYTHONPATH and installed applications:: +- Add social_auth to ``PYTHONPATH`` and installed applications:: INSTALLED_APPS = ( ... @@ -115,11 +115,6 @@ Configuration 'django.contrib.auth.backends.ModelBackend', ) - Note: this was introduced in a recent change and it's not backward - compatible, take into account that saved sessions won't be able to login - because the backend string stored in session (like backends.TwitterBackend) - won't match the new paths. - - The application will try to import custom backends from the sources defined in:: SOCIAL_AUTH_IMPORT_BACKENDS = ( @@ -127,9 +122,9 @@ Configuration ) This way it's easier to add new providers, check the already defined ones - in social_auth.backends for examples. + in ``social_auth.backends`` for examples. - Take into account that backends *must* be defined in AUTHENTICATION_BACKENDS_ + Take into account that backends **must** be defined in AUTHENTICATION_BACKENDS_ or Django won't pick them when trying to authenticate the user. - Setup needed OAuth keys (see OAuth_ section for details):: @@ -157,7 +152,7 @@ Configuration Check Django documentation at `Login URL`_ and `Login redirect URL`_ - If a custom redirect URL is needed that must be different to LOGIN_URL, + If a custom redirect URL is needed that must be different to ``LOGIN_URL``, define the setting:: SOCIAL_AUTH_LOGIN_REDIRECT_URL = '/another-login-url/' @@ -221,18 +216,18 @@ Configuration SOCIAL_AUTH_EXPIRATION = 'expires' - to and use such setting name where expiration times are returned. View that + and use such setting name where expiration times are returned. View that completes login process will set session expiration time using this name if - it's present or 'expires' by default. Expiration time saving can be disabled - setting:: + it's present or ``expires`` by default. Expiration configuration can be disabled + with setting:: SOCIAL_AUTH_SESSION_EXPIRATION = False -- It's possible to override the used User model if needed:: +- It's possible to override the used ``User`` model if needed:: SOCIAL_AUTH_USER_MODEL = 'myapp.CustomUser' - This class *must* have a custom `Model Manager`_ with a create_user method + This class **must** have a custom `Model Manager`_ with a ``create_user`` method that resembles the one on `auth.UserManager`_. Also, it's highly recommended that this class define the following fields:: @@ -246,14 +241,14 @@ Configuration is_authenticated(): ... - These are needed to ensure a better django-auth integration, in other case + These are needed to ensure a better ``django-auth`` integration, in other case `login_required`_ won't be usable. A warning is displayed if any of these are missing. By default `auth.User`_ is used. Check example application for implementation details, but first, please take a look to `User Profiles`_, it might be what you were looking for. - It's possible to disable user creations by django-social-auth with:: + It's possible to disable user creations by ``django-social-auth`` with:: SOCIAL_AUTH_CREATE_USERS = False @@ -268,7 +263,7 @@ Configuration ------- Signals ------- -A pre_update signal is sent when user data is about to be updated with new +A ``pre_update`` signal is sent when user data is about to be updated with new values from authorization service provider, this apply to new users and already existent ones. This is useful to update custom user fields or `User Profiles`_, for example, to store user gender, location, etc. Example:: @@ -287,11 +282,13 @@ signal handler if this setting value is set to True:: SOCIAL_AUTH_CHANGE_SIGNAL_ONLY = False -Take into account that when defining a custom User model and declaring signal -handler in models.py, the imports and handler definition *must* be made after -the custom User model is defined or circular imports issues will be raised. +Take into account that when defining a custom ``User`` model and declaring signal +handler in ``models.py``, the imports and handler definition **must** be made +after the custom ``User`` model is defined or circular imports issues will be +raised. -Also a new-user signal is sent when new accounts are created:: +Also a new-user signal (``socialauth_registered``) is sent when new accounts are +created:: from social_auth.signals import socialauth_registered @@ -309,10 +306,10 @@ OpenId_ support is simpler to implement than OAuth_. Google and Yahoo providers are supported by default, others are supported by POST method providing endpoint URL. -OpenId_ backends can store extra data in UserSocialAuth.extra_data field +OpenId_ backends can store extra data in ``UserSocialAuth.extra_data`` field by defining a set of values names to retrieve from any of the used schemas, -pettributeExchange and SimpleRegistration. As their keywords differ we need -two settings. +``AttributeExchange`` and ``SimpleRegistration``. As their keywords differ we +need two settings. Settings is per backend, so we have two possible values for each one. Name is dynamically checked using uppercase backend name as prefix:: @@ -339,8 +336,8 @@ but provides the option for unregistered applications. Check next sections for details. -OAuth_ backends also can store extra data in UserSocialAuth.extra_data field -by defining a set of values names to retrieve from service response. +OAuth_ backends also can store extra data in ``UserSocialAuth.extra_data`` +field by defining a set of values names to retrieve from service response. Settings is per backend and it's name is dynamically checked using uppercase backend name as prefix:: @@ -358,15 +355,15 @@ alias used to store. ------- Twitter ------- -Twitter offers per application keys named "Consumer Key" and -"Consumer Secret". To enable Twitter these two keys are needed. -Further documentation at `Twitter development resources`_: +Twitter offers per application keys named ``Consumer Key`` and ``Consumer Secret``. +To enable Twitter these two keys are needed. Further documentation at +`Twitter development resources`_: - Register a new application at `Twitter App Creation`_, - mark the "Yes, use Twitter for login" checkbox, and -- fill "Consumer Key" and "Consumer Secret" values:: +- fill ``Consumer Key`` and ``Consumer Secret`` values:: TWITTER_CONSUMER_KEY TWITTER_CONSUMER_SECRET @@ -379,13 +376,13 @@ Further documentation at `Twitter development resources`_: -------- Facebook -------- -Facebook works similar to Twitter but it's simpler to setup and -redirect URL is passed as a parameter when issuing an authorization. -Further documentation at `Facebook development resources`_: +Facebook works similar to Twitter but it's simpler to setup and redirect URL +is passed as a parameter when issuing an authorization. Further documentation +at `Facebook development resources`_: - Register a new application at `Facebook App Creation`_, and -- fill "App Id" and "App Secret" values in values:: +- fill ``App Id`` and ``App Secret`` values in values:: FACEBOOK_APP_ID FACEBOOK_API_SECRET @@ -394,22 +391,22 @@ Further documentation at `Facebook development resources`_: FACEBOOK_EXTENDED_PERMISSIONS = [...] -If you define a redirect URL in Facebook setup page, be sure to not -define http://127.0.0.1:8000 or http://localhost:8000 because it won't -work when testing. Instead I define http://myapp.com and setup a mapping -on /etc/hosts or use dnsmasq_. +If you define a redirect URL in Facebook setup page, be sure to not define +http://127.0.0.1:8000 or http://localhost:8000 because it won't work when +testing. Instead I define http://myapp.com and setup a mapping on /etc/hosts +or use dnsmasq_. ----- Orkut ----- -Orkut offers per application keys named "Consumer Key" and -"Consumer Secret". To enable Orkut these two keys are needed. +Orkut offers per application keys named ``Consumer Key`` and ``Consumer Secret``. +To enable Orkut these two keys are needed. Check `Google support`_ and `Orkut API`_ for details on getting your consumer_key and consumer_secret keys. -- fill "Consumer Key" and "Consumer Secret" values:: +- fill ``Consumer Key`` and ``Consumer Secret`` values:: ORKUT_CONSUMER_KEY ORKUT_CONSUMER_SECRET @@ -426,15 +423,14 @@ your consumer_key and consumer_secret keys. ------------ Google OAuth ------------ -Google provides "Consumer Key" and "Consumer Secret" keys to -registered applications, but also allows unregistered application to -use their authorization system with, but beware that this method -will display a security banner to the user telling that the application -is not trusted. +Google provides ``Consumer Key`` and ``Consumer Secret`` keys to registered +applications, but also allows unregistered application to use their authorization +system with, but beware that this method will display a security banner to the +user telling that the application is not trusted. Check `Google OAuth`_ and make your choice. -- fill "Consumer Key" and "Consumer Secret" values:: +- fill ``Consumer Key`` and ``Consumer Secret`` values:: GOOGLE_CONSUMER_KEY GOOGLE_CONSUMER_SECRET @@ -442,7 +438,6 @@ Check `Google OAuth`_ and make your choice. anonymous values will be used if not configured as described in their `OAuth reference`_ - - configure the display name to be used in the "grant permissions" dialog that Google will display to users in:: @@ -456,21 +451,21 @@ anonymous values will be used if not configured as described in their Check which applications can be included in their `Google Data Protocol Directory`_ + ------------- Google OAuth2 ------------- -Recently Google launched OAuth2 support following the definition at -`OAuth2 draft`. It works in a similar way to plain OAuth mechanism, but -developers *must* register an application and apply for a set of keys. Check -`Google OAuth2`_ document for details. +Recently Google launched OAuth2 support following the definition at `OAuth2 draft`. +It works in a similar way to plain OAuth mechanism, but developers **must** register +an application and apply for a set of keys. Check `Google OAuth2`_ document for details. **Note**: - This support is experimental as Google implementation may change and - OAuth2 is still a draft. + This support is experimental as Google implementation may change and OAuth2 is still + a draft. To enable OAuth2 support: -- fill "Client Key" and "Client Secret" settings, these values can be obtained +- fill ``Client Key`` and ``Client Secret`` settings, these values can be obtained easily as described on `OAuth2 Registering`_ doc:: GOOGLE_OAUTH2_CLIENT_KEY = '' @@ -526,10 +521,10 @@ credentials in the following way:: There's support for Selenium_ tests too on root contrib directory. To run install selenium:: - pip install selenium + $ pip install selenium -and create a test_settings.py copying test_settings.py.template and fill -the needed account information. Then run:: +and create a ``test_settings.py`` copying ``test_settings.py.template`` and +fill the needed account information. Then run:: cd contrib/tests ./runtests.py diff --git a/doc/backends/facebook.rst b/doc/backends/facebook.rst index 7774437..49df886 100644 --- a/doc/backends/facebook.rst +++ b/doc/backends/facebook.rst @@ -1,13 +1,13 @@ Facebook ======== -Facebook works similar to Twitter but it's simpler to setup and -redirect URL is passed as a parameter when issuing an authorization. -Further documentation at `Facebook development resources`_: +Facebook works similar to Twitter but it's simpler to setup and redirect URL +is passed as a parameter when issuing an authorization. Further documentation +at `Facebook development resources`_: - Register a new application at `Facebook App Creation`_, and -- fill **App Id** and **App Secret** values in values:: +- fill ``App Id`` and ``App Secret`` values in values:: FACEBOOK_APP_ID FACEBOOK_API_SECRET @@ -16,10 +16,10 @@ Further documentation at `Facebook development resources`_: FACEBOOK_EXTENDED_PERMISSIONS = [...] -If you define a redirect URL in Facebook setup page, be sure to not -define http://127.0.0.1:8000 or http://localhost:8000 because it won't -work when testing. Instead I define http://myapp.com and setup a mapping -on /etc/hosts or use dnsmasq_. +If you define a redirect URL in Facebook setup page, be sure to not define +http://127.0.0.1:8000 or http://localhost:8000 because it won't work when +testing. Instead I define http://myapp.com and setup a mapping on /etc/hosts +or use dnsmasq_. .. _dnsmasq: http://www.thekelleys.org.uk/dnsmasq/doc.html diff --git a/doc/backends/google.rst b/doc/backends/google.rst index 9062359..c27def7 100644 --- a/doc/backends/google.rst +++ b/doc/backends/google.rst @@ -7,15 +7,14 @@ Google. Google OAuth ------------ -Google provides **Consumer Key** and **Consumer Secret** keys to -registered applications, but also allows unregistered application to -use their authorization system with, but beware that this method -will display a security banner to the user telling that the application -is not trusted. +Google provides ``Consumer Key`` and ``Consumer Secret`` keys to registered +applications, but also allows unregistered application to use their authorization +system with, but beware that this method will display a security banner to the +user telling that the application is not trusted. Check `Google OAuth`_ and make your choice. -- fill **Consumer Key** and **Consumer Secret** values:: +- fill ``Consumer Key`` and ``Consumer Secret`` values:: GOOGLE_CONSUMER_KEY GOOGLE_CONSUMER_SECRET @@ -23,7 +22,6 @@ Check `Google OAuth`_ and make your choice. anonymous values will be used if not configured as described in their `OAuth reference`_ - - configure the display name to be used in the *grant permissions* dialog that Google will display to users in:: @@ -41,18 +39,17 @@ Check which applications can be included in their `Google Data Protocol Director Google OAuth2 ------------- -Recently Google launched OAuth2 support following the definition at -`OAuth2 draft`. It works in a similar way to plain OAuth mechanism, but -developers **must** register an application and apply for a set of keys. Check -`Google OAuth2`_ document for details. +Recently Google launched OAuth2 support following the definition at `OAuth2 draft`. +It works in a similar way to plain OAuth mechanism, but developers **must** register +an application and apply for a set of keys. Check `Google OAuth2`_ document for details. **Note**: - This support is experimental as Google implementation may change and - OAuth2 is still a draft. + This support is experimental as Google implementation may change and OAuth2 is still + a draft. To enable OAuth2 support: -- fill **Client Key** and **Client Secret** settings, these values can be obtained +- fill ``Client Key`` and ``Client Secret`` settings, these values can be obtained easily as described on `OAuth2 Registering`_ doc:: GOOGLE_OAUTH2_CLIENT_KEY = '' @@ -68,13 +65,13 @@ Check which applications can be included in their `Google Data Protocol Director Orkut ----- -Orkut offers per application keys named **Consumer Key** and -**Consumer Secret**. To enable Orkut these two keys are needed. +Orkut offers per application keys named ``Consumer Key`` and ``Consumer Secret``. +To enable Orkut these two keys are needed. Check `Google support`_ and `Orkut API`_ for details on getting your consumer_key and consumer_secret keys. -- fill **Consumer Key** and **Consumer Secret** values:: +- fill ``Consumer Key`` and ``Consumer Secret`` values:: ORKUT_CONSUMER_KEY ORKUT_CONSUMER_SECRET diff --git a/doc/backends/oauth.rst b/doc/backends/oauth.rst index 94304d7..f05b921 100644 --- a/doc/backends/oauth.rst +++ b/doc/backends/oauth.rst @@ -8,8 +8,8 @@ but provides the option for unregistered applications. Check next sections for details. -OAuth_ backends also can store extra data in UserSocialAuth.extra_data field -by defining a set of values names to retrieve from service response. +OAuth_ backends also can store extra data in ``UserSocialAuth.extra_data`` +field by defining a set of values names to retrieve from service response. Settings is per backend and it's name is dynamically checked using uppercase backend name as prefix:: diff --git a/doc/backends/openid.rst b/doc/backends/openid.rst index e096f40..2b8cd59 100644 --- a/doc/backends/openid.rst +++ b/doc/backends/openid.rst @@ -5,9 +5,9 @@ OpenId_ support is simpler to implement than OAuth_. Google and Yahoo providers are supported by default, others are supported by POST method providing endpoint URL. -OpenId_ backends can store extra data in UserSocialAuth.extra_data field +OpenId_ backends can store extra data in ``UserSocialAuth.extra_data`` field by defining a set of values names to retrieve from any of the used schemas, -pettributeExchange and SimpleRegistration. As their keywords differ we need +AttributeExchange and SimpleRegistration. As their keywords differ we need two settings. Settings is per backend, so we have two possible values for each one. Name diff --git a/doc/backends/twitter.rst b/doc/backends/twitter.rst index 961f2fd..f33e8a6 100644 --- a/doc/backends/twitter.rst +++ b/doc/backends/twitter.rst @@ -1,9 +1,9 @@ Twitter ======= -Twitter offers per application keys named "Consumer Key" and -"Consumer Secret". To enable Twitter these two keys are needed. -Further documentation at `Twitter development resources`_: +Twitter offers per application keys named ``Consumer Key`` and ``Consumer Secret``. +To enable Twitter these two keys are needed. Further documentation at +`Twitter development resources`_: - Register a new application at `Twitter App Creation`_, diff --git a/doc/configuration.rst b/doc/configuration.rst index 4e7cbf9..c7645c8 100644 --- a/doc/configuration.rst +++ b/doc/configuration.rst @@ -1,7 +1,7 @@ Configuration ============= -- Add social_auth to PYTHONPATH and installed applications:: +- Add social_auth to ``PYTHONPATH`` and installed applications:: INSTALLED_APPS = ( ... @@ -25,11 +25,6 @@ Configuration 'django.contrib.auth.backends.ModelBackend', ) - Note: this was introduced in a recent change and it's not backward - compatible, take into account that saved sessions won't be able to login - because the backend string stored in session (like backends.TwitterBackend) - won't match the new paths. - - The application will try to import custom backends from the sources defined in:: SOCIAL_AUTH_IMPORT_BACKENDS = ( @@ -37,7 +32,7 @@ Configuration ) This way it's easier to add new providers, check the already defined ones - in social_auth.backends for examples. + in ``social_auth.backends`` for examples. Take into account that backends **must** be defined in AUTHENTICATION_BACKENDS_ or Django won't pick them when trying to authenticate the user. @@ -67,7 +62,7 @@ Configuration Check Django documentation at `Login URL`_ and `Login redirect URL`_ - If a custom redirect URL is needed that must be different to LOGIN_URL, + If a custom redirect URL is needed that must be different to ``LOGIN_URL``, define the setting:: SOCIAL_AUTH_LOGIN_REDIRECT_URL = '/another-login-url/' @@ -131,18 +126,18 @@ Configuration SOCIAL_AUTH_EXPIRATION = 'expires' - to and use such setting name where expiration times are returned. View that + and use such setting name where expiration times are returned. View that completes login process will set session expiration time using this name if - it's present or 'expires' by default. Expiration time saving can be disabled - setting:: + it's present or ``expires`` by default. Expiration configuration can be disabled + with setting:: SOCIAL_AUTH_SESSION_EXPIRATION = False -- It's possible to override the used User model if needed:: +- It's possible to override the used ``User`` model if needed:: SOCIAL_AUTH_USER_MODEL = 'myapp.CustomUser' - This class **must** have a custom `Model Manager`_ with a create_user method + This class **must** have a custom `Model Manager`_ with a ``create_user`` method that resembles the one on `auth.UserManager`_. Also, it's highly recommended that this class define the following fields:: @@ -156,14 +151,14 @@ Configuration is_authenticated(): ... - These are needed to ensure a better django-auth integration, in other case + These are needed to ensure a better ``django-auth`` integration, in other case `login_required`_ won't be usable. A warning is displayed if any of these are missing. By default `auth.User`_ is used. Check example application for implementation details, but first, please take a look to `User Profiles`_, it might be what you were looking for. - It's possible to disable user creations by django-social-auth with:: + It's possible to disable user creations by ``django-social-auth`` with:: SOCIAL_AUTH_CREATE_USERS = False diff --git a/doc/demo.rst b/doc/demo.rst index 5807ce2..0b4dc19 100644 --- a/doc/demo.rst +++ b/doc/demo.rst @@ -2,4 +2,4 @@ Demo ==== There's a demo at http://social.matiasaguirre.net/. -**Note**: It lacks Orkut support at the moment. +**Note**: It lacks some backends support at the moment. diff --git a/doc/installing.rst b/doc/installing.rst index 149f1b6..ae60656 100644 --- a/doc/installing.rst +++ b/doc/installing.rst @@ -11,8 +11,8 @@ Dependencies that **must** be meet to use the application: - OAuth_ support depends on python-oauth2_ -- Twitter and Facebook support demands an application registration - on their corresponding sites. +- Several backends demands application registration on their corresponding + sites. ---------- diff --git a/doc/signals.rst b/doc/signals.rst index 9a9fd20..78b6f76 100644 --- a/doc/signals.rst +++ b/doc/signals.rst @@ -1,6 +1,6 @@ Signals ======= -A pre_update signal is sent when user data is about to be updated with new +A ``pre_update`` signal is sent when user data is about to be updated with new values from authorization service provider, this apply to new users and already existent ones. This is useful to update custom user fields or `User Profiles`_, for example, to store user gender, location, etc. Example:: @@ -19,11 +19,13 @@ signal handler if this setting value is set to True:: SOCIAL_AUTH_CHANGE_SIGNAL_ONLY = False -Take into account that when defining a custom User model and declaring signal -handler in models.py, the imports and handler definition *must* be made after -the custom User model is defined or circular imports issues will be raised. +Take into account that when defining a custom ``User`` model and declaring signal +handler in ``models.py``, the imports and handler definition **must** be made +after the custom ``User`` model is defined or circular imports issues will be +raised. -Also a new-user signal is sent when new accounts are created:: +Also a new-user signal (``socialauth_registered``) is sent when new accounts are +created:: from social_auth.signals import socialauth_registered diff --git a/doc/testing.rst b/doc/testing.rst index 8cb890c..18f5266 100644 --- a/doc/testing.rst +++ b/doc/testing.rst @@ -28,10 +28,10 @@ credentials in the following way:: There's support for Selenium_ tests too on root contrib directory. To run install selenium:: - pip install selenium + $ pip install selenium -and create a test_settings.py copying test_settings.py.template and fill -the needed account information. Then run:: +and create a ``test_settings.py`` copying ``test_settings.py.template`` and +fill the needed account information. Then run:: cd contrib/tests ./runtests.py -- 2.39.5