Fixed #10194: added django.shortcuts.redirect, a do-what-I-mean redirect shortcut. See the docs at topics/http/shortcuts for details.

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

docs/topics/http/shortcuts.txt

@@ -4,16 +4,23 @@
 Django shortcut functions
 =========================
 
+.. module:: django.shortcuts
+   :synopsis:
+       Convience shortcuts that spam multiple levels of Django's MVC stack.
+
+.. index:: shortcuts
+
 The package ``django.shortcuts`` collects helper functions and classes that
 "span" multiple levels of MVC. In other words, these functions/classes
 introduce controlled coupling for convenience's sake.
 
-``render_to_response()``
-========================
+``render_to_response``
+======================
 
-``django.shortcuts.render_to_response`` renders a given template with a given
-context dictionary and returns an ``HttpResponse`` object with that rendered
-text.
+.. function:: render_to_response(template[, dictionary][, context_instance][, mimetype])
+
+   Renders a given template with a given context dictionary and returns an
+   :class:`~django.http.HttpResponse` object with that rendered text.
 
 Required arguments
 ------------------
@@ -42,9 +49,8 @@ Optional arguments
                                   context_instance=RequestContext(request))
 
 ``mimetype``
-
-    .. versionadded:: 1.0
-
+    .. versionadded:: 1.0 
+    
     The MIME type to use for the resulting document. Defaults to the value of
     the :setting:`DEFAULT_CONTENT_TYPE` setting.
 
@@ -73,12 +79,77 @@ This example is equivalent to::
         r = HttpResponse(t.render(c),
             mimetype="application/xhtml+xml")
 
+``redirect``
+============
+
+.. function:: redirect(to[, permanent=False], *args, **kwargs)
+
+   Returns an HttpResponseRedirect to the apropriate URL for the arguments
+   passed.
+   
+   The arguments could be:
+   
+       * A model: the model's `get_absolute_url()` function will be called.
+   
+       * A view name, possibly with arguments: `urlresolvers.reverse()` will
+         be used to reverse-resolve the name.
+        
+       * A URL, which will be used as-is for the redirect location.
+       
+   By default issues a temporary redirect; pass permanent=True to issue a
+   permanent redirect
+   
+Examples
+--------
+
+You can use the :func:`redirect` function in a number of ways.
+
+    1. By passing some object; that object's
+       :meth:`~django.db.models.Model.get_absolute_url` method will be called
+       to figure out the redirect URL::
+       
+            def my_view(request):
+                ...
+                object = MyModel.objects.get(...)
+                return redirect(object)
+                
+    2. By passing the name of a view and optionally some positional or
+       keyword arguments; the URL will be reverse resolved using the
+       :func:`~django.core.urlresolvers.reverse` method::
+       
+            def my_view(request):
+                ...
+                return redirect('some-view-name', foo='bar')
+                
+    3. By passing a hardcoded URL to redirect to::
+    
+            def my_view(request):
+                ...
+                return redirect('/some/url/')
+                
+       This also works with full URLs::
+       
+            def my_view(request):
+                ...
+                return redirect('http://example.com/')
+                
+By default, :func:`redirect` returns a temporary redirect. All of the above
+forms accept a ``permanent`` argument; if set to ``True`` a permanent redirect
+will be returned::
+
+    def my_view(request):
+        ...
+        object = MyModel.objects.get(...)
+        return redirect(object, permanent=True)
+
 ``get_object_or_404``
 =====================
 
-``django.shortcuts.get_object_or_404`` calls
-:meth:`~django.db.models.QuerySet.get()` on a given model manager, but it raises
-``django.http.Http404`` instead of the model's ``DoesNotExist`` exception.
+.. function:: get_object_or_404(object, *args, **kwargs)
+
+   Calls :meth:`~django.db.models.QuerySet.get()` on a given model manager,
+   but it raises ``django.http.Http404`` instead of the model's
+   ``DoesNotExist`` exception.
 
 Required arguments
 ------------------
@@ -118,9 +189,11 @@ raised if more than one object is found.
 ``get_list_or_404``
 ===================
 
-``django.shortcuts.get_list_or_404`` returns the result of
-:meth:`~django.db.models.QuerySet.filter()` on a given model manager, raising
-``django.http.Http404`` if the resulting list is empty.
+.. function:: get_list_or_404(klass, *args, **kwargs)
+
+   Returns the result of :meth:`~django.db.models.QuerySet.filter()` on a
+   given model manager, raising ``django.http.Http404`` if the resulting list
+   is empty.
 
 Required arguments
 ------------------