Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

A whole lotta documentation fixes: Fixes #8704, #8826, #8980, #9243, …

…#9343, #9529,

git-svn-id: http://code.djangoproject.com/svn/django/trunk@10303 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 4d927c7e886f7bda701d8b0225b1df294eb38059 1 parent cd2b7a0
authored March 31, 2009
1  AUTHORS
@@ -242,6 +242,7 @@ answer newbie questions, and generally made Django that much better:
242 242
     konrad@gwu.edu
243 243
     knox <christobzr@gmail.com>
244 244
     David Krauth
  245
+    Kevin Kubasik <kevin@kubasik.net>
245 246
     kurtiss@meetro.com
246 247
     Denis Kuzmichyov <kuzmichyov@gmail.com>
247 248
     Panos Laganakos <panos.laganakos@gmail.com>
5  docs/conf.py
@@ -70,6 +70,11 @@
70 70
 # The name of the Pygments (syntax highlighting) style to use.
71 71
 pygments_style = 'trac'
72 72
 
  73
+# Sphinx will recurse into subversion configuration folders and try to read  
  74
+# any document file within. These should be ignored. 
  75
+# Note: exclude_dirnames is new in Sphinx 0.5 
  76
+exclude_dirnames = ['.svn']
  77
+
73 78
 # Options for HTML output
74 79
 # -----------------------
75 80
 
10  docs/faq/usage.txt
@@ -67,3 +67,13 @@ Using a :class:`~django.db.models.FileField` or an
67 67
        Django. For example, if your :class:`~django.db.models.ImageField` is
68 68
        called ``mug_shot``, you can get the absolute URL to your image in a
69 69
        template with ``{{ object.mug_shot.url }}``.
  70
+
  71
+How do I make a variable available to all my templates?
  72
+-------------------------------------------------------
  73
+
  74
+Sometimes your templates just all need the same thing. A common example would
  75
+be dynamically-generated menus. At first glance, it seems logical to simply
  76
+add a common dictionary to the template context.
  77
+
  78
+The correct solution is to use a ``RequestContext``. Details on how to do this
  79
+are here: :ref:`subclassing-context-requestcontext`.
9  docs/glossary.txt
@@ -13,8 +13,8 @@ Glossary
13 13
         See :ref:`topics-db-models`.
14 14
 
15 15
     generic view
16  
-        A higher-order :term:`view` function that abstracts common idioms and patterns
17  
-        found in view development and abstracts them.
  16
+        A higher-order :term:`view` function that provides an abstract/generic
  17
+        implementation of a common idiom or pattern found in view development.
18 18
         
19 19
         See :ref:`ref-generic-views`.
20 20
 
@@ -71,8 +71,9 @@ Glossary
71 71
         the last bit (``spring``) is the slug.
72 72
 
73 73
     template
74  
-        A chunk of text that separates the presentation of a document from its
75  
-        data.
  74
+        A chunk of text that acts as formatting for representing data. A
  75
+        template helps to abstract the presentation of data from the data
  76
+        itself.
76 77
         
77 78
         See :ref:`topics-templates`.
78 79
         
13  docs/howto/deployment/fastcgi.txt
@@ -288,6 +288,19 @@ You can also run multiple Django installations on the same site simply by
288 288
 specifying multiple entries in the ``fastcgi.server`` directive. Add one
289 289
 FastCGI host for each.
290 290
 
  291
+Cherokee setup
  292
+==============
  293
+
  294
+Cherokee is a very fast, flexible and easy to configure Web Server. It
  295
+supports the widespread technologies nowadays: FastCGI, SCGI, PHP, CGI, SSI,
  296
+TLS and SSL encrypted connections, Virtual hosts, Authentication, on the fly
  297
+encoding, Load Balancing, Apache compatible log files, Data Base Balancer,
  298
+Reverse HTTP Proxy and much more.
  299
+
  300
+The Cherokee project provides a documentation to `setting up Django`_ with Cherokee.
  301
+
  302
+.. _setting up Django: http://www.cherokee-project.com/doc/cookbook_django.html
  303
+
291 304
 Running Django on a shared-hosting provider with Apache
292 305
 =======================================================
293 306
 
1  docs/howto/deployment/index.txt
@@ -13,6 +13,7 @@ ways to easily deploy Django:
13 13
    
14 14
    modwsgi
15 15
    modpython
  16
+   modwsgi
16 17
    fastcgi
17 18
    
18 19
 If you're new to deploying Django and/or Python, we'd recommend you try
4  docs/howto/deployment/modpython.txt
@@ -215,8 +215,10 @@ We recommend using a separate Web server -- i.e., one that's not also running
215 215
 Django -- for serving media. Here are some good choices:
216 216
 
217 217
     * lighttpd_
  218
+    * Nginx_
218 219
     * TUX_
219 220
     * A stripped-down version of Apache_
  221
+    * Cherokee_
220 222
 
221 223
 If, however, you have no option but to serve media files on the same Apache
222 224
 ``VirtualHost`` as Django, here's how you can turn off mod_python for a
@@ -249,8 +251,10 @@ the ``media`` subdirectory and any URL that ends with ``.jpg``, ``.gif`` or
249 251
 
250 252
 
251 253
 .. _lighttpd: http://www.lighttpd.net/
  254
+.. _Nginx: http://wiki.codemongers.com/Main
252 255
 .. _TUX: http://en.wikipedia.org/wiki/TUX_web_server
253 256
 .. _Apache: http://httpd.apache.org/
  257
+.. _Cherokee: http://www.cherokee-project.com/
254 258
 
255 259
 .. _howto-deployment-modpython-serving-the-admin-files:
256 260
 
6  docs/howto/static-files.txt
@@ -10,7 +10,7 @@ How to serve static files
10 10
 Django itself doesn't serve static (media) files, such as images, style sheets,
11 11
 or video. It leaves that job to whichever Web server you choose.
12 12
 
13  
-The reasoning here is that standard Web servers, such as Apache_ and lighttpd_,
  13
+The reasoning here is that standard Web servers, such as Apache_, lighttpd_ and Cherokee_,
14 14
 are much more fine-tuned at serving static files than a Web application
15 15
 framework.
16 16
 
@@ -19,6 +19,7 @@ use the :func:`django.views.static.serve` view to serve media files.
19 19
 
20 20
 .. _Apache: http://httpd.apache.org/
21 21
 .. _lighttpd: http://www.lighttpd.net/
  22
+.. _Cherokee: http://www.cherokee-project.com/
22 23
 
23 24
 The big, fat disclaimer
24 25
 =======================
@@ -72,6 +73,9 @@ required. For example, if we have a line in ``settings.py`` that says::
72 73
     (r'^site_media/(?P<path>.*)$', 'django.views.static.serve',
73 74
             {'document_root': settings.STATIC_DOC_ROOT}),
74 75
 
  76
+Be careful not to use the same path as your :setting:`ADMIN_MEDIA_PREFIX` (which defaults
  77
+to ``/media/``) as this will overwrite your URLconf entry.
  78
+
75 79
 Directory listings
76 80
 ==================
77 81
 
4  docs/intro/tutorial03.txt
@@ -117,8 +117,8 @@ But, don't do that. It's silly.
117 117
 
118 118
 Note that these regular expressions do not search GET and POST parameters, or
119 119
 the domain name. For example, in a request to ``http://www.example.com/myapp/``,
120  
-the URLconf will look for ``/myapp/``. In a request to
121  
-``http://www.example.com/myapp/?page=3``, the URLconf will look for ``/myapp/``.
  120
+the URLconf will look for ``myapp/``. In a request to
  121
+``http://www.example.com/myapp/?page=3``, the URLconf will look for ``myapp/``.
122 122
 
123 123
 If you need help with regular expressions, see `Wikipedia's entry`_ and the
124 124
 `Python documentation`_. Also, the O'Reilly book "Mastering Regular Expressions"
15  docs/ref/contrib/admin/index.txt
@@ -832,8 +832,17 @@ It is important you use a ``ModelForm`` here otherwise things can break. See the
832 832
 ============================
833 833
 
834 834
 The admin interface has the ability to edit models on the same page as a
835  
-parent model. These are called inlines. You can add them to a model by
836  
-specifying them in a ``ModelAdmin.inlines`` attribute::
  835
+parent model. These are called inlines. Suppose you have these two models::
  836
+
  837
+     class Author(models.Model):
  838
+        name = models.CharField(max_length=100)
  839
+
  840
+     class Book(models.Model):
  841
+        author = models.ForeignKey(Author)
  842
+        title = models.CharField(max_length=100)
  843
+
  844
+You can edit the books authored by an author on the author page. You add 
  845
+inlines to a model by specifying them in a ``ModelAdmin.inlines``::
837 846
 
838 847
     class BookInline(admin.TabularInline):
839 848
         model = Book
@@ -1165,7 +1174,7 @@ Hooking ``AdminSite`` instances into your URLconf
1165 1174
 
1166 1175
 The last step in setting up the Django admin is to hook your ``AdminSite``
1167 1176
 instance into your URLconf. Do this by pointing a given URL at the
1168  
-``AdminSite.root`` method.
  1177
+``AdminSite.urls`` method.
1169 1178
 
1170 1179
 In this example, we register the default ``AdminSite`` instance
1171 1180
 ``django.contrib.admin.site`` at the URL ``/admin/`` ::
7  docs/ref/contrib/comments/index.txt
@@ -155,9 +155,10 @@ A complete form might look like::
155 155
     {% get_comment_form for event as form %}
156 156
     <form action="{% comment_form_target %}" method="POST">
157 157
       {{ form }}
158  
-      <p class="submit">
159  
-        <input type="submit" name="preview" class="submit-post" value="Preview">
160  
-      </p>
  158
+      <tr>
  159
+        <td></td>
  160
+        <td><input type="submit" name="preview" class="submit-post" value="Preview"></td>
  161
+      </tr>
161 162
     </form>
162 163
     
163 164
 Be sure to read the `notes on the comment form`_, below, for some special
8  docs/ref/contrib/contenttypes.txt
@@ -324,6 +324,14 @@ same types of lookups manually::
324 324
     ...                           object_id=b.id)
325 325
     [<TaggedItem: django>, <TaggedItem: python>]
326 326
 
  327
+Note that if the model with a :class:`~django.contrib.contenttypes.generic.GenericForeignKey` 
  328
+that you're referring to uses a non-default value for ``ct_field`` or ``fk_field`` 
  329
+(e.g. the :mod:`django.contrib.comments` app uses ``ct_field="object_pk"``), 
  330
+you'll need to pass ``content_type_field`` and ``object_id_field`` to
  331
+:class:`~django.contrib.contenttypes.generic.GenericRelation`.::
  332
+
  333
+	comments = generic.GenericRelation(Comment, content_type_field="content_type", object_id_field="object_pk")
  334
+	
327 335
 Note that if you delete an object that has a
328 336
 :class:`~django.contrib.contenttypes.generic.GenericRelation`, any objects
329 337
 which have a :class:`~django.contrib.contenttypes.generic.GenericForeignKey`
2  docs/ref/contrib/formtools/form-wizard.txt
@@ -290,7 +290,7 @@ Advanced FormWizard methods
290 290
 .. method:: FormWizard.render_template
291 291
 
292 292
     Renders the template for the given step, returning an
293  
-    :class:`~django.http.HttpResponseRedirect` object.
  293
+    :class:`~django.http.HttpResponse` object.
294 294
 
295 295
     Override this method if you want to add a custom context, return a different
296 296
     MIME type, etc. If you only need to override the template name, use
4  docs/ref/databases.txt
@@ -87,8 +87,8 @@ MySQL notes
87 87
 ===========
88 88
 
89 89
 Django expects the database to support transactions, referential integrity,
90  
-and Unicode (UTF-8 encoding). Fortunately, MySQL_ has all these
91  
-features available as far back as 3.23. While it may be possible to use
  90
+and Unicode support (UTF-8 encoding). Fortunately, MySQL_ has all these
  91
+features as available as far back as 3.23. While it may be possible to use
92 92
 3.23 or 4.0, you'll probably have less trouble if you use 4.1 or 5.0.
93 93
 
94 94
 MySQL 4.1
3  docs/ref/django-admin.txt
@@ -341,6 +341,9 @@ would search ``<appname>/fixtures/foo/bar/mydata.json`` for each installed
341 341
 application,  ``<dirname>/foo/bar/mydata.json`` for each directory in
342 342
 ``FIXTURE_DIRS``, and the literal path ``foo/bar/mydata.json``.
343 343
 
  344
+When fixture files are processed, the data is saved to the database as is.
  345
+Model defined ``save`` methods and ``pre_save`` signals are not called.
  346
+
344 347
 Note that the order in which fixture files are processed is undefined. However,
345 348
 all fixture data is installed as a single transaction, so data in
346 349
 one fixture can reference data in another fixture. If the database backend
10  docs/ref/forms/fields.txt
@@ -174,6 +174,16 @@ validation if a particular field's value is not given. ``initial`` values are
174 174
     >>> f.errors
175 175
     {'url': [u'This field is required.'], 'name': [u'This field is required.']}
176 176
 
  177
+Instead of a constant, you can also pass any callable::
  178
+
  179
+    >>> import datetime
  180
+    >>> class DateForm(forms.Form):
  181
+    ...     day = forms.DateField(initial=datetime.date.today)
  182
+    >>> print DateForm()
  183
+    <tr><th>Day:</th><td><input type="text" name="day" value="12/23/2008" /><td></tr>
  184
+
  185
+The callable will be evaluated only when the unbound form is displayed, not when it is defined.
  186
+
177 187
 ``widget``
178 188
 ~~~~~~~~~~
179 189
 
40  docs/ref/models/fields.txt
@@ -7,6 +7,8 @@ Model field reference
7 7
 .. module:: django.db.models.fields
8 8
    :synopsis: Built-in field types.
9 9
 
  10
+.. currentmodule:: django.db.models
  11
+
10 12
 This document contains all the gory details about all the `field options`_ and
11 13
 `field types`_ Django's got to offer.
12 14
 
@@ -45,11 +47,11 @@ booleans and dates. For both types of fields, you will also need to set
45 47
 :attr:`~Field.blank`).
46 48
 
47 49
 Avoid using :attr:`~Field.null` on string-based fields such as
48  
-:class:`~django.db.models.CharField` and :class:`~django.db.models.TextField`
49  
-unless you have an excellent reason. If a string-based field has ``null=True``,
50  
-that means it has two possible values for "no data": ``NULL``, and the empty
51  
-string. In most cases, it's redundant to have two possible values for "no
52  
-data;" Django convention is to use the empty string, not ``NULL``.
  50
+:class:`CharField` and :class:`TextField` unless you have an excellent reason.
  51
+If a string-based field has ``null=True``, that means it has two possible values
  52
+for "no data": ``NULL``, and the empty string. In most cases, it's redundant to
  53
+have two possible values for "no data;" Django convention is to use the empty
  54
+string, not ``NULL``.
53 55
 
54 56
 .. note::
55 57
 
@@ -142,9 +144,8 @@ documentation.
142 144
 Finally, note that choices can be any iterable object -- not necessarily a list
143 145
 or tuple. This lets you construct choices dynamically. But if you find yourself
144 146
 hacking :attr:`~Field.choices` to be dynamic, you're probably better off using a
145  
-proper database table with a :class:`~django.db.models.ForeignKey`.
146  
-:attr:`~Field.choices` is meant for static data that doesn't change much, if
147  
-ever.
  147
+proper database table with a :class:`ForeignKey`. :attr:`~Field.choices` is
  148
+meant for static data that doesn't change much, if ever.
148 149
 
149 150
 ``db_column``
150 151
 -------------
@@ -220,10 +221,10 @@ Alternatively you can use plain text and
220 221
 If ``True``, this field is the primary key for the model.
221 222
 
222 223
 If you don't specify ``primary_key=True`` for any fields in your model, Django
223  
-will automatically add an :class:`~django.db.models.IntegerField` to hold the
224  
-primary key, so you don't need to set ``primary_key=True`` on any of your
225  
-fields unless you want to override the default primary-key behavior. For more,
226  
-see :ref:`automatic-primary-key-fields`.
  224
+will automatically add an :class:`IntegerField` to hold the primary key, so you
  225
+don't need to set ``primary_key=True`` on any of your fields unless you want to
  226
+override the default primary-key behavior. For more, see
  227
+:ref:`automatic-primary-key-fields`.
227 228
 
228 229
 ``primary_key=True`` implies :attr:`null=False <Field.null>` and :attr:`unique=True <Field.unique>`.
229 230
 Only one primary key is allowed on an object.
@@ -240,18 +241,16 @@ you try to save a model with a duplicate value in a :attr:`~Field.unique`
240 241
 field, a :exc:`django.db.IntegrityError` will be raised by the model's
241 242
 :meth:`~django.db.models.Model.save` method.
242 243
 
243  
-This option is valid on all field types except
244  
-:class:`~django.db.models.ManyToManyField` and
245  
-:class:`~django.db.models.FileField`.
  244
+This option is valid on all field types except :class:`ManyToManyField` and
  245
+:class:`FileField`.
246 246
 
247 247
 ``unique_for_date``
248 248
 -------------------
249 249
 
250 250
 .. attribute:: Field.unique_for_date
251 251
 
252  
-Set this to the name of a :class:`~django.db.models.DateField` or
253  
-:class:`~django.db.models.DateTimeField` to require that this field be unique
254  
-for the value of the date field.
  252
+Set this to the name of a :class:`DateField` or :class:`DateTimeField` to
  253
+require that this field be unique for the value of the date field.
255 254
 
256 255
 For example, if you have a field ``title`` that has
257 256
 ``unique_for_date="pub_date"``, then Django wouldn't allow the entry of two
@@ -734,7 +733,10 @@ A :class:`CharField` for a URL. Has one extra optional argument:
734 733
 .. attribute:: URLField.verify_exists
735 734
 
736 735
     If ``True`` (the default), the URL given will be checked for existence
737  
-    (i.e., the URL actually loads and doesn't give a 404 response).
  736
+    (i.e., the URL actually loads and doesn't give a 404 response). It should
  737
+    be noted that when using the single-threaded development server, validating
  738
+    a url being serverd by the same server will hang.
  739
+    This should not be a problem for multithreaded servers.
738 740
 
739 741
 The admin represents this as an ``<input type="text">`` (a single-line input).
740 742
 
14  docs/ref/models/querysets.txt
@@ -154,7 +154,7 @@ In SQL terms, that evaluates to::
154 154
 
155 155
     SELECT ...
156 156
     WHERE NOT pub_date > '2005-1-3'
157  
-    AND NOT headline = 'Hello'
  157
+    OR NOT headline = 'Hello'
158 158
 
159 159
 Note the second example is more restrictive.
160 160
 
@@ -1484,8 +1484,18 @@ search
1484 1484
 A boolean full-text search, taking advantage of full-text indexing. This is
1485 1485
 like ``contains`` but is significantly faster due to full-text indexing.
1486 1486
 
  1487
+Example::
  1488
+    
  1489
+    Entry.objects.filter(headline__search="+Django -jazz Python")
  1490
+
  1491
+SQL equivalent::
  1492
+
  1493
+    SELECT ... WHERE MATCH(tablename, headline) AGAINST (+Django -jazz Python IN BOOLEAN MODE);
  1494
+
1487 1495
 Note this is only available in MySQL and requires direct manipulation of the
1488  
-database to add the full-text index.
  1496
+database to add the full-text index. By default Django uses BOOLEAN MODE for
  1497
+full text searches. `Please check MySQL documentation for additional details. <http://dev.mysql.com/doc/refman/5.1/en/fulltext-boolean.html>`_
  1498
+
1489 1499
 
1490 1500
 regex
1491 1501
 ~~~~~
2  docs/ref/models/relations.txt
@@ -42,7 +42,7 @@ Extra methods on managers when used in a ForeignKey context
42 42
         ....     body_text='Hi', 
43 43
         ....     pub_date=datetime.date(2005, 1, 1)
44 44
         .... )
45  
-        >>> e.save()
  45
+        >>> e.save(force_insert=True)
46 46
 
47 47
     Note that there's no need to specify the keyword argument of the model that
48 48
     defines the relationship. In the above example, we don't pass the parameter
4  docs/ref/signals.txt
@@ -30,6 +30,10 @@ module system.
30 30
     If you override these methods on your model, you must call the parent class'
31 31
     methods for this signals to be sent.
32 32
 
  33
+	Note also that Django stores signal handlers as weak references by default,
  34
+	so if your handler is a local function, it may be garbage collected.  To
  35
+	prevent this, pass ``weak=False`` when you call the signal's :meth:`~django.dispatch.Signal.connect`.
  36
+
33 37
 pre_init
34 38
 --------
35 39
 
47  docs/topics/auth.txt
@@ -463,6 +463,12 @@ When a user profile model has been defined and specified in this manner, each
463 463
 instance of the user profile model associated with that
464 464
 :class:`~django.contrib.auth.models.User`.
465 465
 
  466
+The method :class:`~django.contrib.auth.models.User.get_profile()`
  467
+does not create the profile, if it does not exist. You need to
  468
+register a handler for the signal
  469
+:attr:`django.db.models.signals.post_save` on the User model, and, in
  470
+the handler, if created=True, create the associated user profile.
  471
+
466 472
 For more information, see `Chapter 12 of the Django book`_.
467 473
 
468 474
 .. _Chapter 12 of the Django book: http://www.djangobook.com/en/1.0/chapter12/#cn222
@@ -745,7 +751,7 @@ the following line to your URLconf::
745 751
         <p>Your username and password didn't match. Please try again.</p>
746 752
         {% endif %}
747 753
 
748  
-        <form method="post" action="">
  754
+        <form method="post" action="{% url django.contrib.auth.views.login %}">
749 755
         <table>
750 756
         <tr>
751 757
             <td>{{ form.username.label_tag }}</td>
@@ -868,6 +874,34 @@ includes a few other useful built-in views located in
868 874
         * ``login_url``: The URL of the login page to redirect to. This will
869 875
           default to :setting:`settings.LOGIN_URL <LOGIN_URL>` if not supplied.
870 876
 
  877
+.. function:: password_reset_confirm(request[,uidb36, token, template_name, token_generator, set_password_form, post_reset_redirect])
  878
+
  879
+    Presents a form for entering a new password.
  880
+
  881
+    **Optional arguments:**
  882
+
  883
+        * ``uidb36``: The user's id encoded in base 36. This will default to
  884
+          ``None``.
  885
+        * ``token``: Token to check that the password is valid. This will default to ``None``.
  886
+        * ``template_name``: The full name of a template to display the confirm
  887
+          password view. Default value is :file:`registration/password_reset_confirm.html`.
  888
+        * ``token_generator``: Instance of the class to check the password. This
  889
+          will default to ``default_token_generator``, it's an instance of
  890
+          ``django.contrib.auth.tokens.PasswordResetTokenGenerator``.
  891
+        * ``set_password_form``: Form that will use to set the password. This will 
  892
+          default to ``SetPasswordForm``.
  893
+        * ``post_reset_redirect``: URL to redirect after the password reset
  894
+          done. This will default to ``None``.
  895
+
  896
+.. function:: password_reset_complete(request[,template_name])
  897
+
  898
+   Presents a view that informs that the password has been changed very well.
  899
+
  900
+   **Optional arguments:** 
  901
+
  902
+       * ``template_name``: The full name of a template to display the view.
  903
+         This will default to :file:`registration/password_reset_complete.html`.
  904
+
871 905
 Built-in forms
872 906
 --------------
873 907
 
@@ -1125,10 +1159,10 @@ The currently logged-in user and his/her permissions are made available in the
1125 1159
 Users
1126 1160
 -----
1127 1161
 
1128  
-The currently logged-in user, either a
1129  
-:class:`~django.contrib.auth.models.User` instance or an
1130  
-:class:`~django.contrib.auth.models.AnonymousUser` instance, is stored in the
1131  
-template variable ``{{ user }}``:
  1162
+When rendering a template :class:`~django.template.context.RequestContext`, the
  1163
+currently logged-in user, either a  :class:`~django.contrib.auth.models.User`
  1164
+instance or an :class:`~django.contrib.auth.models.AnonymousUser` instance, is
  1165
+stored in the template variable ``{{ user }}``:
1132 1166
 
1133 1167
 .. code-block:: html
1134 1168
 
@@ -1138,6 +1172,9 @@ template variable ``{{ user }}``:
1138 1172
         <p>Welcome, new user. Please log in.</p>
1139 1173
     {% endif %}
1140 1174
 
  1175
+This template context variable is not available if a ``RequestContext`` is not
  1176
+being used.
  1177
+
1141 1178
 Permissions
1142 1179
 -----------
1143 1180
 
2  docs/topics/http/shortcuts.txt
@@ -26,7 +26,7 @@ Required arguments
26 26
 ------------------
27 27
 
28 28
 ``template``
29  
-    The full name of a template to use.
  29
+    The full name of a template to use or sequence of template names.
30 30
 
31 31
 Optional arguments
32 32
 ------------------
34  docs/topics/http/urls.txt
@@ -633,6 +633,40 @@ reverse such patterns.
633 633
     be imported correctly. Do not include lines that reference views you
634 634
     haven't written yet, because those views will not be importable.
635 635
 
  636
+resolve()
  637
+---------
  638
+
  639
+The :func:`django.core.urlresolvers.resolve` function can be used for resolving
  640
+URL paths to the corresponding view functions. It has the following signature:
  641
+
  642
+.. currentmodule:: django.core.urlresolvers
  643
+.. function:: resolve(path, urlconf=None)
  644
+
  645
+``path`` is the URL path you want to resolve. As with ``reverse()`` above, you
  646
+don't need to worry about the ``urlconf`` parameter. The function returns the
  647
+triple (view function, arguments, keyword arguments).
  648
+
  649
+For example, it can be used for testing if a view would raise a ``Http404``
  650
+error before redirecting to it::
  651
+
  652
+    from urlparse import urlparse
  653
+    from django.core.urlresolvers import resolve
  654
+    from django.http import HttpResponseRedirect, Http404
  655
+
  656
+    def myview(request):
  657
+        next = request.META.get('HTTP_REFERER', None) or '/'
  658
+        response = HttpResponseRedirect(next)
  659
+
  660
+        # modify the request and response as required, e.g. change locale
  661
+        # and set corresponding locale cookie
  662
+
  663
+        view, args, kwargs = resolve(urlparse(next)[2])
  664
+        kwargs['request'] = request
  665
+        try:
  666
+            view(*args, **kwargs)
  667
+        except Http404:
  668
+            return HttpResponseRedirect('/')
  669
+        return response
636 670
 
637 671
 permalink()
638 672
 -----------
9  docs/topics/testing.txt
@@ -138,10 +138,11 @@ and execute those lines while checking that the results match.
138 138
 In the case of model tests, note that the test runner takes care of creating
139 139
 its own test database. That is, any test that accesses a database -- by
140 140
 creating and saving model instances, for example -- will not affect your
141  
-production database. Each doctest begins with a "blank slate" -- a fresh
142  
-database containing an empty table for each model. (See the section on
143  
-fixtures, below, for more on this.) Note that to use this feature, the database
144  
-user Django is connecting as must have ``CREATE DATABASE`` rights.
  141
+production database. However, the database is not refreshed between doctests,
  142
+so if your doctest requires a certain state you should consider flushin the 
  143
+database or loading a fixture. (See the section on fixtures, below, for more 
  144
+on this.) Note that to use this feature, the database user Django is connecting
  145
+as must have ``CREATE DATABASE`` rights.
145 146
 
146 147
 For more details about how doctest works, see the `standard library
147 148
 documentation for doctest`_.

0 notes on commit 4d927c7

Please sign in to comment.
Something went wrong with that request. Please try again.