Improve pipeline documentation

[shoooe]

The documentation regarding the pipeline is basic to say the least. I think that each step of at least the default pipeline should be described:

    'social.pipeline.social_auth.social_details',
    'social.pipeline.social_auth.social_uid',
    'social.pipeline.social_auth.auth_allowed',
    'social.pipeline.social_auth.social_user',
    'social.pipeline.user.get_username',
    'social.pipeline.user.create_user',
    'social.pipeline.social_auth.associate_user',
    'social.pipeline.social_auth.load_extra_data',
    'social.pipeline.user.user_details'

What does 'social.pipeline.social_auth.social_details' do, for example? Which steps does 'social.pipeline.social_auth.social_user' depend on? And so on.

The code is not documented, so it's hard to tell what parts can be customized and where.

[wadewilliams]

fwiw,

# Get the information we can about the user.
'social.pipeline.social_auth.social_details',

# Get the social uid from whichever service we're authing thru
'social.pipeline.social_auth.social_uid',

# Some sort of authorization that has nothing to do with whether or not the user granted permissions or not
'social.pipeline.social_auth.auth_allowed',

# Checking the usersocialauth table for pre-existing connections
'social.pipeline.social_auth.social_user',

# Make up a username for this person
'social.pipeline.user.get_username',

# 'social.pipeline.mail.mail_validation',

# Checking against user table for email if we don't have them yet
'social.pipeline.social_auth.associate_by_email',

# Create a user if we haven't found one yet
'social.pipeline.user.create_user',

# Create the socialauth connection record for this user.
'social.pipeline.social_auth.associate_user',


'social.pipeline.social_auth.load_extra_data',
'authentication.services.authentication.socialSendActivationEmail',

# Update the user record with any changed info from social.
'social.pipeline.user.user_details',

That might not be 100% correct but its atleast my understanding of it at this point.

[omab]

Comments added (https://github.com/omab/python-social-auth/blob/1b56357c5a8365310507e89385457b1d3df9781b/social/pipeline/__init__.py) and also in docs http://psa.matiasaguirre.net/docs/pipeline.html.

[shoooe]

Exactly what I was looking for, thanks @wadewilliams.