Finalized docs for release

doc/activation.rst

@@ -1,2 +1,113 @@
+.. _activation:
+
 User Activation
 ***************
+
+Many web applications require some form of user activation, usually to verify
+user-provided information such as email addresses. django-user-profiles provides
+an activation module, implemented as a Django application.
+
+
+Installation
+============
+
+- In order to enable activation, add the ``activation`` module to your
+  ``INSTALLED_APPS`` setting::
+
+    INSTALLED_APPS = (
+        # ... your other apps here 
+        'user_profiles',
+        'user_profiles.activation',
+    )
+
+- Include the activation URLconf in your ``urls.py``::
+
+    urlpatterns = patterns('',
+        # ... your urls here
+        (r'^user/', include('user_profiles.activation.urls')),
+    )
+
+.. note::
+   Whenever new user sign up, they will now be sent an activation request via
+   email. However, if you want to prevent new users from logging in unless they
+   have activated, you need to set :ref:`USER_PROFILES_USER_SET_ACTIVE_ON_SIGNUP
+   <user-profiles-user-set-active-on-signup>` to ``False`` in your project's
+   settings module. Sometimes you also need to re-request activation from users,
+   for instance when they change their email address. See
+   :ref:`activation-utility` for more information.
+
+This application automatically connects to the ``post_signup`` signal dispatched
+by django-user-profiles in order send to request activation from new users.
+See the :ref:`signals documentation <user-profiles-signals>` for more
+information.
+
+
+.. _activation-templates:
+
+Message templates
+=================
+
+For rendering the activation request email, text templates are used. You are
+likely to require your own customized messages. To customize the email text,
+simply your own templates with the following names: 
+
+``activation/email/activation_request.subject.txt``
+    The subject line of the activation email. 
+
+``activation/email/activation_request.txt``
+    The body text of the activation email. This should display the activation
+    key to the user, plus a link to the activation page and form. Example template::
+ 
+        Dear {{ recipient }}, please go to {{ url }} to activate your account.
+        If the above link doesn't work, go to {{ form_url }} and enter the
+        following key: {{ key }}
+    
+
+The following context variables are available to both of these templates:
+
+``url``
+    The activation link URL
+
+``form_url``
+    The link to the activation form
+
+``site_url``
+    The link to the website that requires activation
+
+``site``
+    The corresponding ``Site`` object
+
+``key``
+    The activation key
+
+``user``
+    The associated ``User`` object
+
+``recipient``
+    An object that resolves to a string containing the name of the user (i.e.
+    either the user or the profile object, depending on whether the profile
+    model has a ``__unicode__`` method).
+
+``profile``
+    The associated user profile object.
+
+``created``
+    If the user was just created, this will ``True``. If the user already
+    existed, it will be ``False``. You are probably going to want to address
+    users in a different way if the just signed up.
+
+
+Views
+=====
+
+.. automodule:: user_profiles.activation.views
+   :members:
+
+.. _activation-utility:
+
+Utility functions
+=================
+
+.. autofunction:: user_profiles.activation.utils.require_activation_from_user
+
+.. autofunction:: user_profiles.activation.utils.accept_activation_code

doc/configuration.rst

@@ -1,3 +1,5 @@
+.. _configuration:
+
 Configuring django-user-profiles
 ********************************
 
@@ -26,13 +28,15 @@ USER_PROFILES_URL_FIELD
     The field of the user profile model used to generate URLs to profile pages.
     You could replace this by a slug field, for instance.
 
+.. _user-profiles-user-set-active-on-signup:
+
 USER_PROFILES_USER_SET_ACTIVE_ON_SIGNUP
     Default: ``True``
 
     Specifies whether the ``is_active`` field of a user object should be set to
     ``True`` on signup, immediately enabling the user to log in. If this is
     disabled, further activation is necessary, for instance using the activation
-    module provided by django-user-profiles.
+    module provided by this application. See :ref:`activation`.
 
 
 USER_PROFILES_EMAIL_AS_USERNAME
@@ -42,3 +46,21 @@ USER_PROFILES_EMAIL_AS_USERNAME
     enabled, email addresses and usernames will be kept synchronized, and users
     log in with their email address instead of specifying a username. 
 
+USER_PROFILES_PUBLIC
+    Default: ``False``
+
+    Specifies whether all user profiles should be visible to any user, including
+    anonymous visitors. Set this to ``False`` if users should not be able to see
+    the information of other users.
+
+    .. warning::
+       Making user profiles public could pose serious privacy and security
+       violations.
+
+USER_PROFILES_PUBLIC_WHEN_LOGGED_IN
+    Default: ``False``
+
+    Specifies whether all user profiles should be visible to any logged-in user.
+    Set this to ``False`` if users should not be able to see the information of
+    other users.
+

doc/dummy/models.py

@@ -0,0 +1,4 @@
+from django.db import models
+
+class Profile(models.Model):
+    pass

doc/dummy/settings.py

@@ -1,5 +1,7 @@
 # Django settings for dummy project.
 
+IS_SPHINX_BUILD_DUMMY = True
+
 DEBUG = True
 TEMPLATE_DEBUG = DEBUG
 
@@ -143,3 +145,5 @@
         },
     }
 }
+
+AUTH_PROFILE_MODULE = 'dummy.Profile'

doc/forms.rst

@@ -1,2 +1,7 @@
+.. _forms:
+
 User Forms
-**********
+**********
+
+.. automodule:: user_profiles.forms
+   :members:

doc/index.rst

@@ -6,8 +6,8 @@ Introduction
 
 django-user-profiles is a flexible app that wires together Django's user
 authentication and user profile features, with customizable forms and models.
-Furthermore, it provides a layer for user profile activation, plus support for a
-multiple-profiles-per-user feature.
+Furthermore, it provides a module for user profile activation, plus basic
+support for a multiple-profiles-per-user feature.
 
 
 Table of Contents
@@ -18,13 +18,14 @@ Table of Contents
 
    overview
    installation
+   configuration
    models
+   managers
    views
-   configuration
    activation
    multiple-profiles
    forms
-   templatetags
+   signals
    other
 
 

doc/installation.rst

@@ -1,2 +1,40 @@
 Installing django-user-profiles
 *******************************
+
+.. note::
+   Please refer to the Django documentation on `storing additional information
+   about users
+   <https://docs.djangoproject.com/en/1.3/topics/auth/#storing-additional-information-about-users>`_
+   for more information about how Django handles user profiles.
+
+- Create a user profile model subclassing
+  ``user_profiles.models.UserProfileBase``, and define it in your project
+  settings (see :ref:`models`)::
+
+    AUTH_PROFILE_MODULE = 'my_app.MyUserProfile'
+   
+- Add the ``user_profiles`` module to your ``INSTALLED_APPS`` setting::
+
+    INSTALLED_APPS = (
+        # ... your other apps here 
+        'user_profiles',
+    )
+
+- Add ``user_profiles.middleware.CurrentUserMiddleware`` to your ``MIDDLEWARE_CLASSES``::
+
+    MIDDLEWARE_CLASSES = (
+        # ... your other middleware classes here 
+        'user_profiles.middleware.CurrentUserMiddleware',
+    )
+
+
+- Include the URLconf in your ``urls.py``::
+
+    urlpatterns = patterns('',
+        # ... your urls here
+        (r'^user/', include('user_profiles.urls')),
+    )
+
+- If you want to enable user activation, you also need to install that module.
+  See :ref:`activation`. 
+

doc/managers.rst

@@ -1,2 +1,5 @@
 Model Managers
-**************
+**************
+
+.. automodule:: user_profiles.managers
+   :members:

doc/middleware.rst

@@ -1,5 +1,9 @@
+.. _middleware:
+
 Middleware
 **********
 
 .. automodule:: user_profiles.middleware
-   :members:
+   :members:
+
+

doc/models.rst

@@ -1,3 +1,5 @@
+.. _models:
+
 User Profile Models
 *******************
 

doc/multiple-profiles.rst

@@ -1,2 +1,26 @@
 Implementing a multiple-profiles-per-user feature
-*************************************************
+*************************************************
+
+This application provides very basic support for implementing a web site where
+one user can have several profiles (as in different sets of contact
+information), with one being their default profile that is returned by Django's
+``user.get_profile()`` method. This is achieved by filtering profile objects
+by the ``is_default`` field. Please see the :ref:`user profile base model
+<models>` for more information on this subject.
+
+Currently, django-user-profiles comes without any views for creating,
+displaying, updating or deleting additional profiles (although this might change
+in the future). You are responsible for creating such views yourself.
+
+These views can be pretty standard, following the basic CRUD concept as seen in
+most Django applications. You can use the standard model form provided by
+django-user-profiles, and of course you need to make sure that users can only
+edit their own profiles.
+
+.. warning::
+   If you are implementing a multiple-profiles-per-user feature in your project,
+   you should prevent users from deleting their default profile by checking
+   first whether ``is_default`` is ``True``. When creating additonal profiles
+   for a user, you also need to make sure that the ``is_default`` field is
+   ``True`` for exactly one profile object so as not to create any ambiguities
+   that lead to errors. 

doc/other.rst

@@ -1,11 +1,10 @@
-Secondary features
-******************
+Secondary features and fixes
+****************************
 
 .. toctree::
    :maxdepth: 2
 
    middleware
    admin
-   managers
    patches
 

doc/overview.rst

@@ -3,8 +3,8 @@ Overview
 
 django-user-profiles is a flexible app that wires together Django's user
 authentication and user profile features, with customizable forms and models.
-Furthermore, it provides a layer for user profile activation, plus support for a
-multiple-profiles-per-user feature.
+Furthermore, it provides a module for user profile activation, plus basic
+support for a multiple-profiles-per-user feature.
 
 This app also aims to offer some improvements where the standard
 ``django.contrib.auth`` app falls short.

doc/signals.rst

@@ -0,0 +1,10 @@
+.. _user-profiles-signals:
+
+Signals
+*******
+
+django-user-profiles provides the following signals that you can connect to if
+you need specific code to be executed on certain events.
+
+.. automodule:: user_profiles.signals
+   :members:

doc/views.rst

@@ -1,2 +1,5 @@
 User Views
 **********
+
+.. automodule:: user_profiles.views
+   :members:

user_profiles/activation/models.py

@@ -6,6 +6,10 @@
 import uuid
 
 class ActivationCode(models.Model):
+    """
+    An ``ActivationCode`` object is a key and user pair. If the accurate key
+    is provided, the user can be activated.
+    """
     key = models.CharField(max_length=32, editable=False)
     user = models.ForeignKey(User, editable=False)
     activated = models.BooleanField(editable=False, default=False)
@@ -18,6 +22,10 @@ def save(self, *args, **kwargs):
         super(ActivationCode, self).save(*args, **kwargs)
 
 def post_signup_send_activation_link_to_new_user(sender, **kwargs):
+    """
+    This is the signal handler for the ``post_signup`` signal dispatched by
+    the user_profiles app. It sends an activation request to the new user. 
+    """
     from user_profiles.activation.utils import send_activation_link_to_user
     send_activation_link_to_user(kwargs['user'], created=True)
 

user_profiles/activation/urls.py

@@ -1,8 +1,8 @@
 from django.conf.urls.defaults import *
 
 urlpatterns = patterns('',
-    url(r'^activation/send/$', 'user_profiles.activation.views.current_user_send', name='user_profiles_activation_current_user_send'),
-    url(r'^activation/([a-z0-9]+)/$', 'user_profiles.activation.views.activate', name='user_profiles_activation_activate'),
+    url(r'^activation/send/$', 'user_profiles.activation.views.send_activation_code_to_user', name='user_profiles_send_activation_code_to_user'),
+    url(r'^activation/([a-z0-9]+)/$', 'user_profiles.activation.views.activate', name='user_profiles_activate'),
     url(r'^activation/$', 'user_profiles.activation.views.activate', name='user_profiles_activation_form'),
 )