Docs: harmonize examples & clarify when to use `setup_activation` (recommended in README but not in the Wiki)

[jankoegel]

Configuration

• Sorcery Version: latest

Expected Behavior

The docs should be clear and not say two different things in two places.

Actual Behavior

The README recommends the following steps to activate a user:

User.load_from_activation_token(token)
@user.setup_activation
@user.activate!

This suggests that a call to setup_activation is required to activate a user. In the Wiki, however, setup_activation is omitted (and only mentioned at the very bottom in an example for resending the activation email):

if @user = User.load_from_activation_token(params[:id])
  @user.activate!
  redirect_to(login_path, :notice => 'User was successfully activated.')

Source for setup_activation at the time of writing:

sorcery/lib/sorcery/model/submodules/user_activation.rb

Lines 90 to 96 in 6fdc703

	def setup_activation
	config = sorcery_config
	generated_activation_token = TemporaryToken.generate_random_token
	send(:"#{config.activation_token_attribute_name}=", generated_activation_token)
	send(:"#{config.activation_state_attribute_name}=", 'pending')
	send(:"#{config.activation_token_expires_at_attribute_name}=", Time.now.in_time_zone + config.activation_token_expiration_period) if config.activation_token_expiration_period
	end

Desired changes

• clarify in the docs when a call to setup_activation is needed
• harmonize the examples in the README and the Wiki so no confusion about when it's required to call setup_activation.

Steps to Reproduce

Doesn't apply.

[willnet]

@jankoegel Thank you for the suggestion. I added an explanation of setup_activation to the wiki. Please let me know if it needs further improvement.

[jankoegel]

@willnet iirc the most confusing thing for me was that the README calls the following:

1. User.load_from_activation_token
2. User#setup_activation
3. User#activate!

Whereas the Wiki still skips step 2. Shouldn't we add step 2 to the Wiki as well?

[willnet]

@jankoegel I reread the implementation of UserActivation.
Since setup_activation is implicitly called when a user is created,
It seems we don’t need to call it explicitly except when changing the email. I noted at the bottom of the wiki that it’s required when changing the email.
The order of methods listed under User Activation in the README doesn’t seem to have any particular meaning—it’s just a list of related methods.
Adding a brief explanation of what setup_activation does, like the following, might be helpful.
What do you think about this kind of change?

User.load_from_activation_token(token)
@user.setup_activation # Generate a token for activation. Implicitly called when creating a user with a password. Explicitly called when updating the email or similar situations.
@user.activate!