Reference

README.rst

@@ -55,7 +55,8 @@ Installation
 4. Add ``SESSION_ENGINE = 'user_sessions.backends.db'``.
 5. Add ``url(r'', include('user_sessions.urls', 'user_sessions')),`` to your
    ``urls.py``.
-6. Run ``python manage.py syncdb`` (or ``migrate``) and start hacking!
+6. Run ``python manage.py syncdb`` (or ``migrate``) and browse to 
+   ``/account/sessions/``.
 
 GeoIP
 -----

docs/index.rst

@@ -14,6 +14,7 @@ Contents:
    installation
    usage
    reference
+   release-notes
 
 
 Indices and tables

docs/reference.rst

@@ -1,10 +1,28 @@
 Reference
 =========
 
+Middleware
+----------
+.. autoclass:: user_sessions.middleware.SessionMiddleware
+
+Models
+------
+.. autoclass:: user_sessions.models.Session
+
+Session Backends
+----------------
+.. autoclass:: user_sessions.backends.db.SessionStore
+
+Template Tags
+-------------
+.. automodule:: user_sessions.templatetags.user_sessions
+   :members:
+
+Views
+-----
 .. autoclass:: user_sessions.views.SessionListView
 .. autoclass:: user_sessions.views.SessionDeleteView
 
 Unit tests
 ----------
-
-.. autoclass:: user_sessions.utils.
+.. autoclass:: user_sessions.utils.tests.Client

docs/release-notes.rst

@@ -0,0 +1,15 @@
+Release Notes
+=============
+
+0.1.2
+-----
+* Ship with default templates
+* Added Dutch translation
+
+0.1.1
+-----
+* Added South migrations
+
+0.1.0
+-----
+* Initial release

docs/usage.rst

@@ -6,30 +6,44 @@ Current session
 The current session is available on the request, just like the normal session
 middleware makes the session available::
 
-	def my_view(request):
-		request.session
+    def my_view(request):
+        request.session
 
 
 All sessions
 ------------
 To get the list of a user's sessions::
 
-	sessions = user.session_set.filter(expire_date__gt=now())
+    sessions = user.session_set.filter(expire_date__gt=now())
 
 You could logout the user everywhere::
 
     user.session_set.all().delete()
 
+
 Generic views
 -------------
 There are two views included with this application, 
 :class:`~user_sessions.views.SessionListView` and 
 :class:`~user_sessions.views.SessionDeleteView`. Using this views you have a
-simple, but effective, user session management that even looks great without
-any additional styling:
+simple, but effective, user session management that even looks great out of 
+the box:
 
 .. image:: _static/custom-view.png
 
+Template tags
+~~~~~~~~~~~~~
+Two template tags are included 
+:meth:`~user_sessions.templatetags.user_sessions.device` and
+:meth:`~user_sessions.templatetags.user_sessions.location`. These can be used
+for respectively humanizing the user agent string and showing an approximate
+location of the IP address::
+
+    {% load user_sessions %}
+    {{ session.user_agent|device }} -> Safari on OS X
+    {{ session.ip|location }}       -> Zwolle, The Netherlands
+
+
 Admin views
 -----------
 

user_sessions/middleware.py

@@ -7,6 +7,9 @@
 
 
 class SessionMiddleware(object):
+    """
+    Middleware that provides ip and user_agent to the session store.
+    """
     def process_request(self, request):
         engine = import_module(settings.SESSION_ENGINE)
         session_key = request.COOKIES.get(settings.SESSION_COOKIE_NAME, None)

user_sessions/models.py

@@ -7,20 +7,16 @@
 
 class Session(models.Model):
     """
+    Session objects containing user session information.
+
     Django provides full support for anonymous sessions. The session
     framework lets you store and retrieve arbitrary data on a
     per-site-visitor basis. It stores data on the server side and
     abstracts the sending and receiving of cookies. Cookies contain a
     session ID -- not the data itself.
 
-    The Django sessions framework is entirely cookie-based. It does
-    not fall back to putting session IDs in URLs. This is an intentional
-    design decision. Not only does that behavior make URLs ugly, it makes
-    your site vulnerable to session-ID theft via the "Referer" header.
-
-    For complete documentation on using Sessions in your code, consult
-    the sessions documentation that is shipped with Django (also available
-    on the Django Web site).
+    Additionally this session object providers the following properties:
+    ``user``, ``user_agent`` and ``ip``.
     """
     session_key = models.CharField(_('session key'), max_length=40,
                                    primary_key=True)

user_sessions/templatetags/user_sessions.py

@@ -32,6 +32,16 @@
 
 @register.filter
 def device(value):
+    """
+    Transform a User Agent into a human readable text.
+
+    Example output:
+
+    * Safari on iPhone
+    * Chrome on Windows 8.1
+    * Safari on OS X
+    """
+
     for regex, name in BROWSERS:
         if regex.search(value):
             browser = name
@@ -50,6 +60,14 @@ def device(value):
 
 @register.filter
 def location(value):
+    """
+    Transform an IP address into an approximate location.
+
+    Example output:
+
+    * Zwolle, The Netherlands
+    * ``<i>unknown</i>``
+    """
     location = geoip() and geoip().city(value)
     if location and location['country_name']:
         if location['city']: