Tidy up the sessions documentation creating links for session methods and crosslinking settings

git-svn-id: http://code.djangoproject.com/svn/django/trunk@16245 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/topics/http/sessions.txt

@@ -17,14 +17,15 @@ Sessions are implemented via a piece of :doc:`middleware </ref/middleware>`.
 
 To enable session functionality, do the following:
 
-    * Edit the ``MIDDLEWARE_CLASSES`` setting and make sure
-      ``MIDDLEWARE_CLASSES`` contains ``'django.contrib.sessions.middleware.SessionMiddleware'``.
-      The default ``settings.py`` created by ``django-admin.py startproject`` has
-      ``SessionMiddleware`` activated.
+    * Edit the :setting:`MIDDLEWARE_CLASSES` setting and make sure
+      it contains ``'django.contrib.sessions.middleware.SessionMiddleware'``.
+      The default ``settings.py`` created by ``django-admin.py startproject``
+      has ``SessionMiddleware`` activated.
 
 If you don't want to use sessions, you might as well remove the
-``SessionMiddleware`` line from ``MIDDLEWARE_CLASSES`` and ``'django.contrib.sessions'``
-from your ``INSTALLED_APPS``. It'll save you a small bit of overhead.
+``SessionMiddleware`` line from ``MIDDLEWARE_CLASSES`` and
+``'django.contrib.sessions'`` from your :setting:`INSTALLED_APPS`.
+It'll save you a small bit of overhead.
 
 Configuring the session engine
 ==============================
@@ -86,56 +87,62 @@ configuration instructions for the `using database-backed sessions`_.
 Using file-based sessions
 -------------------------
 
-To use file-based sessions, set the ``SESSION_ENGINE`` setting to
+To use file-based sessions, set the :setting:`SESSION_ENGINE` setting to
 ``"django.contrib.sessions.backends.file"``.
 
-You might also want to set the ``SESSION_FILE_PATH`` setting (which defaults
-to output from ``tempfile.gettempdir()``, most likely ``/tmp``) to control
-where Django stores session files. Be sure to check that your Web server has
-permissions to read and write to this location.
+You might also want to set the :setting:`SESSION_FILE_PATH` setting (which
+defaults to output from ``tempfile.gettempdir()``, most likely ``/tmp``) to
+control where Django stores session files. Be sure to check that your Web
+server has permissions to read and write to this location.
 
 
 Using sessions in views
 =======================
 
-When ``SessionMiddleware`` is activated, each ``HttpRequest`` object -- the
-first argument to any Django view function -- will have a ``session``
-attribute, which is a dictionary-like object. You can read it and write to it.
+When ``SessionMiddleware`` is activated, each :class:`~django.http.HttpRequest`
+object -- the first argument to any Django view function -- will have a
+``session`` attribute, which is a dictionary-like object.
 
-A session object has the following standard dictionary methods:
+You can read it and write to ``request.session`` at any point in your view.
+You can edit it multiple times.
 
-    * ``__getitem__(key)``
+.. class:: backends.base.SessionBase
+
+    This is the base class for all session objects. It has the following
+    standard dictionary methods:
+
+    .. method:: __getitem__(key)
 
       Example: ``fav_color = request.session['fav_color']``
 
-    * ``__setitem__(key, value)``
+    .. method:: __setitem__(key, value)
 
       Example: ``request.session['fav_color'] = 'blue'``
 
-    * ``__delitem__(key)``
+    .. method:: __delitem__(key)
 
       Example: ``del request.session['fav_color']``. This raises ``KeyError``
       if the given ``key`` isn't already in the session.
 
-    * ``__contains__(key)``
+    .. method:: __contains__(key)
 
       Example: ``'fav_color' in request.session``
 
-    * ``get(key, default=None)``
+    .. method:: get(key, default=None)
 
       Example: ``fav_color = request.session.get('fav_color', 'red')``
 
-    * ``keys()``
+    .. method:: keys
 
-    * ``items()``
+    .. method:: items
 
-    * ``setdefault()``
+    .. method:: setdefault
 
-    * ``clear()``
+    .. method:: clear
 
-It also has these methods:
+    It also has these methods:
 
-    * ``flush()``
+    .. method:: flush
 
       Delete the current session data from the session and regenerate the
       session key value that is sent back to the user in the cookie. This is
@@ -143,25 +150,25 @@ It also has these methods:
       accessed again from the user's browser (for example, the
       :func:`django.contrib.auth.logout()` function calls it).
 
-    * ``set_test_cookie()``
+    .. method:: set_test_cookie
 
       Sets a test cookie to determine whether the user's browser supports
       cookies. Due to the way cookies work, you won't be able to test this
       until the user's next page request. See `Setting test cookies`_ below for
       more information.
 
-    * ``test_cookie_worked()``
+    .. method:: test_cookie_worked
 
       Returns either ``True`` or ``False``, depending on whether the user's
       browser accepted the test cookie. Due to the way cookies work, you'll
       have to call ``set_test_cookie()`` on a previous, separate page request.
       See `Setting test cookies`_ below for more information.
 
-    * ``delete_test_cookie()``
+    .. method:: delete_test_cookie
 
       Deletes the test cookie. Use this to clean up after yourself.
 
-    * ``set_expiry(value)``
+    .. method:: set_expiry(value)
 
       Sets the expiration time for the session. You can pass a number of
       different values:
@@ -184,26 +191,23 @@ It also has these methods:
       purposes. Session expiration is computed from the last time the
       session was *modified*.
 
-    * ``get_expiry_age()``
+    .. method:: get_expiry_age
 
       Returns the number of seconds until this session expires. For sessions
       with no custom expiration (or those set to expire at browser close), this
-      will equal ``settings.SESSION_COOKIE_AGE``.
+      will equal :setting:`SESSION_COOKIE_AGE`.
 
-    * ``get_expiry_date()``
+    .. method:: get_expiry_date
 
       Returns the date this session will expire. For sessions with no custom
       expiration (or those set to expire at browser close), this will equal the
-      date ``settings.SESSION_COOKIE_AGE`` seconds from now.
+      date :setting:`SESSION_COOKIE_AGE` seconds from now.
 
-    * ``get_expire_at_browser_close()``
+    .. method:: get_expire_at_browser_close
 
       Returns either ``True`` or ``False``, depending on whether the user's
       session cookie will expire when the user's Web browser is closed.
 
-You can edit ``request.session`` at any point in your view. You can edit it
-multiple times.
-
 Session object guidelines
 -------------------------
 
@@ -249,25 +253,29 @@ This simplistic view logs in a "member" of the site::
             pass
         return HttpResponse("You're logged out.")
 
-The standard ``django.contrib.auth.logout()`` function actually does a bit
-more than this to prevent inadvertent data leakage. It calls
-``request.session.flush()``. We are using this example as a demonstration of
-how to work with session objects, not as a full ``logout()`` implementation.
+The standard :meth:`django.contrib.auth.logout` function actually does a bit
+more than this to prevent inadvertent data leakage. It calls the
+:meth:`~backends.base.SessionBase.flush` method of ``request.session``.
+We are using this example as a demonstration of how to work with session
+objects, not as a full ``logout()`` implementation.
 
 Setting test cookies
 ====================
 
 As a convenience, Django provides an easy way to test whether the user's
-browser accepts cookies. Just call ``request.session.set_test_cookie()`` in a
-view, and call ``request.session.test_cookie_worked()`` in a subsequent view --
+browser accepts cookies. Just call the
+:meth:`~backends.base.SessionBase.set_test_cookie` method of
+``request.session`` in a view, and call
+:meth:`~backends.base.SessionBase.test_cookie_worked` in a subsequent view --
 not in the same view call.
 
 This awkward split between ``set_test_cookie()`` and ``test_cookie_worked()``
 is necessary due to the way cookies work. When you set a cookie, you can't
 actually tell whether a browser accepted it until the browser's next request.
 
-It's good practice to use ``delete_test_cookie()`` to clean up after yourself.
-Do this after you've verified that the test cookie worked.
+It's good practice to use
+:meth:`~backends.base.SessionBase.delete_test_cookie()` to clean up after
+yourself. Do this after you've verified that the test cookie worked.
 
 Here's a typical usage example::
 
@@ -346,9 +354,9 @@ the session object::
 
     request.session.modified = True
 
-To change this default behavior, set the ``SESSION_SAVE_EVERY_REQUEST`` setting
-to ``True``. If ``SESSION_SAVE_EVERY_REQUEST`` is ``True``, Django will save
-the session to the database on every single request.
+To change this default behavior, set the :setting:`SESSION_SAVE_EVERY_REQUEST`
+setting to ``True``. When set to ``True``, Django will save the session to the
+database on every single request.
 
 Note that the session cookie is only sent when a session has been created or
 modified. If ``SESSION_SAVE_EVERY_REQUEST`` is ``True``, the session cookie
@@ -361,12 +369,13 @@ Browser-length sessions vs. persistent sessions
 ===============================================
 
 You can control whether the session framework uses browser-length sessions vs.
-persistent sessions with the ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` setting.
+persistent sessions with the :setting:`SESSION_EXPIRE_AT_BROWSER_CLOSE`
+setting.
 
 By default, ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` is set to ``False``, which
 means session cookies will be stored in users' browsers for as long as
-``SESSION_COOKIE_AGE``. Use this if you don't want people to have to log in
-every time they open a browser.
+:setting:`SESSION_COOKIE_AGE`. Use this if you don't want people to have to
+log in every time they open a browser.
 
 If ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` is set to ``True``, Django will use
 browser-length cookies -- cookies that expire as soon as the user closes his or
@@ -374,8 +383,8 @@ her browser. Use this if you want people to have to log in every time they open
 a browser.
 
 This setting is a global default and can be overwritten at a per-session level
-by explicitly calling ``request.session.set_expiry()`` as described above in
-`using sessions in views`_.
+by explicitly calling the :meth:`~backends.base.SessionBase.set_expiry` method
+of ``request.session`` as described above in `using sessions in views`_.
 
 Clearing the session table
 ==========================
@@ -397,7 +406,8 @@ in the past -- but your application may have different requirements.
 Settings
 ========
 
-A few :doc:`Django settings </ref/settings>` give you control over session behavior:
+A few :doc:`Django settings </ref/settings>` give you control over session
+behavior:
 
 SESSION_ENGINE
 --------------