From 71796410ba8e292a39610a4435f7693ca37b4289 Mon Sep 17 00:00:00 2001
From: Adrian Holovaty <adrian@holovaty.com>
Date: Fri, 14 Sep 2007 22:33:06 +0000
Subject: [PATCH] Fixed #5474 -- Improved docs/shortcuts.txt. Thanks, minarets
 and EyePulp

git-svn-id: http://code.djangoproject.com/svn/django/trunk@6234 bcc190cf-cafb-0310-a4f2-bffc1f526a37
---
 docs/shortcuts.txt | 120 +++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 111 insertions(+), 9 deletions(-)

diff --git a/docs/shortcuts.txt b/docs/shortcuts.txt
index 2c0dbb5663..6c55486b5f 100644
--- a/docs/shortcuts.txt
+++ b/docs/shortcuts.txt
@@ -6,36 +6,138 @@ 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.
 
-Example::
+Required arguments
+------------------
+
+``template``
+    The full name of a template to use.
+
+Optional arguments
+------------------
+
+``context``
+    A dictionary of values to add to the template context. By default, this
+    is an empty dictionary. If a value in the dictionary is callable, the
+    view will call it just before rendering  the template.
+
+``mimetype``
+    **New in Django development version:** The MIME type to use for the
+    resulting document. Defaults to the value of the ``DEFAULT_CONTENT_TYPE``
+    setting.
+
+Example
+-------
+
+The following example renders the template ``myapp/index.html`` with the
+MIME type ``application/xhtml+xml``::
 
     from django.shortcuts import render_to_response
-    r = render_to_response('myapp/template.html', {'foo': 'bar'})
+
+    def my_view(request):
+        # View code here...
+        return render_to_response('myapp/index.html', {"foo": "bar"},
+            mimetype="application/xhtml+xml")
 
 This example is equivalent to::
 
     from django.http import HttpResponse
     from django.template import Context, loader
-    t = loader.get_template('myapp/template.html')
-    c = Context({'foo': 'bar'})
-    r = HttpResponse(t.render(c))
+
+    def my_view(request):
+        # View code here...
+        t = loader.get_template('myapp/template.html')
+        c = Context({'foo': 'bar'})
+        r = HttpResponse(t.render(c),
+            mimetype="application/xhtml+xml")
+
+.. _an HttpResponse object: ../request_response/#httpresponse-objects
 
 ``get_object_or_404``
 =====================
 
-``django.shortcuts.get_object_or_404`` calls ``get()`` on a given model
+``django.shortcuts.get_object_or_404`` calls `get()`_ on a given model
 manager, but it raises ``django.http.Http404`` instead of the model's
 ``DoesNotExist`` exception.
 
+Required arguments
+------------------
+
+``klass``
+    A ``Model``, ``Manager`` or ``QuerySet`` instance from which to get the
+    object.
+
+``**kwargs``
+    Lookup parameters, which should be in the format accepted by ``get()`` and
+    ``filter()``.
+
+Example
+-------
+
+The following example gets the object with the primary key of 1 from
+``MyModel``::
+
+    from django.shortcuts import get_object_or_404
+
+    def my_view(request):
+        my_object = get_object_or_404(MyModel, pk=1)
+
+This example is equivalent to::
+
+    from django.http import Http404
+
+    def my_view(request):
+        try:
+            my_object = MyModel.object.get(pk=1)
+        except MyModel.DoesNotExist:
+            raise Http404
+
+Note: As with ``get()``, an ``AssertionError`` will be raised if more than
+one object is found.
+
+.. _get(): ../db-api/#get-kwargs
+
 ``get_list_or_404``
 ===================
 
-``django.shortcuts.get_list_or_404`` returns the result of ``filter()`` on a
+``django.shortcuts.get_list_or_404`` returns the result of `filter()`_ on a
 given model manager, raising ``django.http.Http404`` if the resulting list is
 empty.
+
+Required arguments
+------------------
+
+``klass``
+    A ``Model``, ``Manager`` or ``QuerySet`` instance from which to get the
+    object.
+
+``**kwargs``
+    Lookup parameters, which should be in the format accepted by ``get()`` and
+    ``filter()``.
+
+Example
+-------
+
+The following example gets all published objects from ``MyModel``::
+
+    from django.shortcuts import get_list_or_404
+
+    def my_view(request):
+        my_objects = get_list_or_404(MyModel, published=True)
+
+This example is equivalent to::
+
+    from django.http import Http404
+
+    def my_view(request):
+        my_objects = MyModels.object.filter(published=True)
+        if not my_objects:
+            raise Http404
+
+.. _filter(): ../db-api/#filter-kwargs