[1.0.X] A whole lotta documentation fixes, backported from r10303 on trunk.

I got my commit message cut off the first try, but luckily I get to still thank Kevin Kubasik for rolling all these fixes up into a single easy patch.

git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.0.X@10306 bcc190cf-cafb-0310-a4f2-bffc1f526a37

AUTHORS

@@ -233,6 +233,7 @@ answer newbie questions, and generally made Django that much better:
     konrad@gwu.edu
     knox <christobzr@gmail.com>
     David Krauth
+    Kevin Kubasik <kevin@kubasik.net>
     kurtiss@meetro.com
     Denis Kuzmichyov <kuzmichyov@gmail.com>
     Panos Laganakos <panos.laganakos@gmail.com>

docs/conf.py

@@ -68,6 +68,11 @@ show_authors = False
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'trac'
 
+# Sphinx will recurse into subversion configuration folders and try to read  
+# any document file within. These should be ignored. 
+# Note: exclude_dirnames is new in Sphinx 0.5 
+exclude_dirnames = ['.svn']
+
 # Options for HTML output
 # -----------------------
 

docs/faq/usage.txt

@@ -67,3 +67,13 @@ Using a :class:`~django.db.models.FileField` or an
        Django. For example, if your :class:`~django.db.models.ImageField` is
        called ``mug_shot``, you can get the absolute URL to your image in a
        template with ``{{ object.mug_shot.url }}``.
+
+How do I make a variable available to all my templates?
+-------------------------------------------------------
+
+Sometimes your templates just all need the same thing. A common example would
+be dynamically-generated menus. At first glance, it seems logical to simply
+add a common dictionary to the template context.
+
+The correct solution is to use a ``RequestContext``. Details on how to do this
+are here: :ref:`subclassing-context-requestcontext`.

docs/glossary.txt

@@ -13,8 +13,8 @@ Glossary
         See :ref:`topics-db-models`.
 
     generic view
-        A higher-order :term:`view` function that abstracts common idioms and patterns
+        A higher-order :term:`view` function that provides an abstract/generic
-        found in view development and abstracts them.
+        implementation of a common idiom or pattern found in view development.
         
         See :ref:`ref-generic-views`.
 
@@ -71,8 +71,9 @@ Glossary
         the last bit (``spring``) is the slug.
 
     template
-        A chunk of text that separates the presentation of a document from its
+        A chunk of text that acts as formatting for representing data. A
-        data.
+        template helps to abstract the presentation of data from the data
+        itself.
         
         See :ref:`topics-templates`.
         

docs/howto/deployment/fastcgi.txt

@@ -288,6 +288,19 @@ You can also run multiple Django installations on the same site simply by
 specifying multiple entries in the ``fastcgi.server`` directive. Add one
 FastCGI host for each.
 
+Cherokee setup
+==============
+
+Cherokee is a very fast, flexible and easy to configure Web Server. It
+supports the widespread technologies nowadays: FastCGI, SCGI, PHP, CGI, SSI,
+TLS and SSL encrypted connections, Virtual hosts, Authentication, on the fly
+encoding, Load Balancing, Apache compatible log files, Data Base Balancer,
+Reverse HTTP Proxy and much more.
+
+The Cherokee project provides a documentation to `setting up Django`_ with Cherokee.
+
+.. _setting up Django: http://www.cherokee-project.com/doc/cookbook_django.html
+
 Running Django on a shared-hosting provider with Apache
 =======================================================
 

docs/howto/deployment/index.txt

@@ -13,6 +13,7 @@ ways to easily deploy Django:
    
    modwsgi
    modpython
+   modwsgi
    fastcgi
    
 If you're new to deploying Django and/or Python, we'd recommend you try

docs/howto/deployment/modpython.txt

@@ -215,8 +215,10 @@ We recommend using a separate Web server -- i.e., one that's not also running
 Django -- for serving media. Here are some good choices:
 
     * lighttpd_
+    * Nginx_
     * TUX_
     * A stripped-down version of Apache_
+    * Cherokee_
 
 If, however, you have no option but to serve media files on the same Apache
 ``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
 
 
 .. _lighttpd: http://www.lighttpd.net/
+.. _Nginx: http://wiki.codemongers.com/Main
 .. _TUX: http://en.wikipedia.org/wiki/TUX_web_server
 .. _Apache: http://httpd.apache.org/
+.. _Cherokee: http://www.cherokee-project.com/
 
 .. _howto-deployment-modpython-serving-the-admin-files:
 

docs/howto/static-files.txt

@@ -10,7 +10,7 @@ How to serve static files
 Django itself doesn't serve static (media) files, such as images, style sheets,
 or video. It leaves that job to whichever Web server you choose.
 
-The reasoning here is that standard Web servers, such as Apache_ and lighttpd_,
+The reasoning here is that standard Web servers, such as Apache_, lighttpd_ and Cherokee_,
 are much more fine-tuned at serving static files than a Web application
 framework.
 
@@ -19,6 +19,7 @@ use the :func:`django.views.static.serve` view to serve media files.
 
 .. _Apache: http://httpd.apache.org/
 .. _lighttpd: http://www.lighttpd.net/
+.. _Cherokee: http://www.cherokee-project.com/
 
 The big, fat disclaimer
 =======================
@@ -72,6 +73,9 @@ required. For example, if we have a line in ``settings.py`` that says::
     (r'^site_media/(?P<path>.*)$', 'django.views.static.serve',
             {'document_root': settings.STATIC_DOC_ROOT}),
 
+Be careful not to use the same path as your :setting:`ADMIN_MEDIA_PREFIX` (which defaults
+to ``/media/``) as this will overwrite your URLconf entry.
+
 Directory listings
 ==================
 

docs/intro/tutorial03.txt

@@ -117,8 +117,8 @@ But, don't do that. It's silly.
 
 Note that these regular expressions do not search GET and POST parameters, or
 the domain name. For example, in a request to ``http://www.example.com/myapp/``,
-the URLconf will look for ``/myapp/``. In a request to
+the URLconf will look for ``myapp/``. In a request to
-``http://www.example.com/myapp/?page=3``, the URLconf will look for ``/myapp/``.
+``http://www.example.com/myapp/?page=3``, the URLconf will look for ``myapp/``.
 
 If you need help with regular expressions, see `Wikipedia's entry`_ and the
 `Python documentation`_. Also, the O'Reilly book "Mastering Regular Expressions"

docs/ref/contrib/admin.txt

@@ -678,8 +678,17 @@ It is important you use a ``ModelForm`` here otherwise things can break. See the
 ============================
 
 The admin interface has the ability to edit models on the same page as a
-parent model. These are called inlines. You can add them to a model by
+parent model. These are called inlines. Suppose you have these two models::
-specifying them in a ``ModelAdmin.inlines`` attribute::
+
+     class Author(models.Model):
+        name = models.CharField(max_length=100)
+
+     class Book(models.Model):
+        author = models.ForeignKey(Author)
+        title = models.CharField(max_length=100)
+
+You can edit the books authored by an author on the author page. You add 
+inlines to a model by specifying them in a ``ModelAdmin.inlines``::
 
     class BookInline(admin.TabularInline):
         model = Book
@@ -1012,7 +1021,7 @@ Hooking ``AdminSite`` instances into your URLconf
 
 The last step in setting up the Django admin is to hook your ``AdminSite``
 instance into your URLconf. Do this by pointing a given URL at the
-``AdminSite.root`` method.
+``AdminSite.urls`` method.
 
 In this example, we register the default ``AdminSite`` instance
 ``django.contrib.admin.site`` at the URL ``/admin/`` ::

docs/ref/contrib/comments/index.txt

@@ -155,9 +155,10 @@ A complete form might look like::
     {% get_comment_form for event as form %}
     <form action="{% comment_form_target %}" method="POST">
       {{ form }}
-      <p class="submit">
+      <tr>
-        <input type="submit" name="preview" class="submit-post" value="Preview">
+        <td></td>
-      </p>
+        <td><input type="submit" name="preview" class="submit-post" value="Preview"></td>
+      </tr>
     </form>
     
 Be sure to read the `notes on the comment form`_, below, for some special

docs/ref/contrib/contenttypes.txt

@@ -324,6 +324,14 @@ same types of lookups manually::
     ...                           object_id=b.id)
     [<TaggedItem: django>, <TaggedItem: python>]
 
+Note that if the model with a :class:`~django.contrib.contenttypes.generic.GenericForeignKey` 
+that you're referring to uses a non-default value for ``ct_field`` or ``fk_field`` 
+(e.g. the :mod:`django.contrib.comments` app uses ``ct_field="object_pk"``), 
+you'll need to pass ``content_type_field`` and ``object_id_field`` to
+:class:`~django.contrib.contenttypes.generic.GenericRelation`.::
+
+	comments = generic.GenericRelation(Comment, content_type_field="content_type", object_id_field="object_pk")
+	
 Note that if you delete an object that has a
 :class:`~django.contrib.contenttypes.generic.GenericRelation`, any objects
 which have a :class:`~django.contrib.contenttypes.generic.GenericForeignKey`

docs/ref/contrib/formtools/form-wizard.txt

@@ -290,7 +290,7 @@ Advanced FormWizard methods
 .. method:: FormWizard.render_template
 
     Renders the template for the given step, returning an
-    :class:`~django.http.HttpResponseRedirect` object.
+    :class:`~django.http.HttpResponse` object.
 
     Override this method if you want to add a custom context, return a different
     MIME type, etc. If you only need to override the template name, use

docs/ref/databases.txt

@@ -19,8 +19,8 @@ MySQL notes
 ===========
 
 Django expects the database to support transactions, referential integrity,
-and Unicode (UTF-8 encoding). Fortunately, MySQL_ has all these
+and Unicode support (UTF-8 encoding). Fortunately, MySQL_ has all these
-features available as far back as 3.23. While it may be possible to use
+features as available as far back as 3.23. While it may be possible to use
 3.23 or 4.0, you'll probably have less trouble if you use 4.1 or 5.0.
 
 MySQL 4.1

docs/ref/django-admin.txt

@@ -338,6 +338,9 @@ would search ``<appname>/fixtures/foo/bar/mydata.json`` for each installed
 application,  ``<dirname>/foo/bar/mydata.json`` for each directory in
 ``FIXTURE_DIRS``, and the literal path ``foo/bar/mydata.json``.
 
+When fixture files are processed, the data is saved to the database as is.
+Model defined ``save`` methods and ``pre_save`` signals are not called.
+
 Note that the order in which fixture files are processed is undefined. However,
 all fixture data is installed as a single transaction, so data in
 one fixture can reference data in another fixture. If the database backend

docs/ref/forms/fields.txt

@@ -174,6 +174,16 @@ validation if a particular field's value is not given. ``initial`` values are
     >>> f.errors
     {'url': [u'This field is required.'], 'name': [u'This field is required.']}
 
+Instead of a constant, you can also pass any callable::
+
+    >>> import datetime
+    >>> class DateForm(forms.Form):
+    ...     day = forms.DateField(initial=datetime.date.today)
+    >>> print DateForm()
+    <tr><th>Day:</th><td><input type="text" name="day" value="12/23/2008" /><td></tr>
+
+The callable will be evaluated only when the unbound form is displayed, not when it is defined.
+
 ``widget``
 ~~~~~~~~~~
 

docs/ref/models/fields.txt

@@ -7,6 +7,8 @@ Model field reference
 .. module:: django.db.models.fields
    :synopsis: Built-in field types.
 
+.. currentmodule:: django.db.models
+
 This document contains all the gory details about all the `field options`_ and
 `field types`_ Django's got to offer.
 
@@ -45,11 +47,11 @@ booleans and dates. For both types of fields, you will also need to set
 :attr:`~Field.blank`).
 
 Avoid using :attr:`~Field.null` on string-based fields such as
-:class:`~django.db.models.CharField` and :class:`~django.db.models.TextField`
+:class:`CharField` and :class:`TextField` unless you have an excellent reason.
-unless you have an excellent reason. If a string-based field has ``null=True``,
+If a string-based field has ``null=True``, that means it has two possible values
-that means it has two possible values for "no data": ``NULL``, and the empty
+for "no data": ``NULL``, and the empty string. In most cases, it's redundant to
-string. In most cases, it's redundant to have two possible values for "no
+have two possible values for "no data;" Django convention is to use the empty
-data;" Django convention is to use the empty string, not ``NULL``.
+string, not ``NULL``.
 
 .. note::
 
@@ -142,9 +144,8 @@ documentation.
 Finally, note that choices can be any iterable object -- not necessarily a list
 or tuple. This lets you construct choices dynamically. But if you find yourself
 hacking :attr:`~Field.choices` to be dynamic, you're probably better off using a
-proper database table with a :class:`~django.db.models.ForeignKey`.
+proper database table with a :class:`ForeignKey`. :attr:`~Field.choices` is
-:attr:`~Field.choices` is meant for static data that doesn't change much, if
+meant for static data that doesn't change much, if ever.
-ever.
 
 ``db_column``
 -------------
@@ -220,10 +221,10 @@ Alternatively you can use plain text and
 If ``True``, this field is the primary key for the model.
 
 If you don't specify ``primary_key=True`` for any fields in your model, Django
-will automatically add an :class:`~django.db.models.IntegerField` to hold the
+will automatically add an :class:`IntegerField` to hold the primary key, so you
-primary key, so you don't need to set ``primary_key=True`` on any of your
+don't need to set ``primary_key=True`` on any of your fields unless you want to
-fields unless you want to override the default primary-key behavior. For more,
+override the default primary-key behavior. For more, see
-see :ref:`automatic-primary-key-fields`.
+:ref:`automatic-primary-key-fields`.
 
 ``primary_key=True`` implies :attr:`null=False <Field.null>` and :attr:`unique=True <Field.unique>`.
 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`
 field, a :exc:`django.db.IntegrityError` will be raised by the model's
 :meth:`~django.db.models.Model.save` method.
 
-This option is valid on all field types except
+This option is valid on all field types except :class:`ManyToManyField` and
-:class:`~django.db.models.ManyToManyField` and
+:class:`FileField`.
-:class:`~django.db.models.FileField`.
 
 ``unique_for_date``
 -------------------
 
 .. attribute:: Field.unique_for_date
 
-Set this to the name of a :class:`~django.db.models.DateField` or
+Set this to the name of a :class:`DateField` or :class:`DateTimeField` to
-:class:`~django.db.models.DateTimeField` to require that this field be unique
+require that this field be unique for the value of the date field.
-for the value of the date field.
 
 For example, if you have a field ``title`` that has
 ``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:
 .. attribute:: URLField.verify_exists
 
     If ``True`` (the default), the URL given will be checked for existence
-    (i.e., the URL actually loads and doesn't give a 404 response).
+    (i.e., the URL actually loads and doesn't give a 404 response). It should
+    be noted that when using the single-threaded development server, validating
+    a url being serverd by the same server will hang.
+    This should not be a problem for multithreaded servers.
 
 The admin represents this as an ``<input type="text">`` (a single-line input).
 

docs/ref/models/querysets.txt

@@ -154,7 +154,7 @@ In SQL terms, that evaluates to::
 
     SELECT ...
     WHERE NOT pub_date > '2005-1-3'
-    AND NOT headline = 'Hello'
+    OR NOT headline = 'Hello'
 
 Note the second example is more restrictive.
 
@@ -1250,8 +1250,18 @@ search
 A boolean full-text search, taking advantage of full-text indexing. This is
 like ``contains`` but is significantly faster due to full-text indexing.
 
+Example::
+    
+    Entry.objects.filter(headline__search="+Django -jazz Python")
+
+SQL equivalent::
+
+    SELECT ... WHERE MATCH(tablename, headline) AGAINST (+Django -jazz Python IN BOOLEAN MODE);
+
 Note this is only available in MySQL and requires direct manipulation of the
-database to add the full-text index.
+database to add the full-text index. By default Django uses BOOLEAN MODE for
+full text searches. `Please check MySQL documentation for additional details. <http://dev.mysql.com/doc/refman/5.1/en/fulltext-boolean.html>`_
+
 
 regex
 ~~~~~

docs/ref/models/relations.txt

@@ -42,7 +42,7 @@ Extra methods on managers when used in a ForeignKey context
         ....     body_text='Hi', 
         ....     pub_date=datetime.date(2005, 1, 1)
         .... )
-        >>> e.save()
+        >>> e.save(force_insert=True)
 
     Note that there's no need to specify the keyword argument of the model that
     defines the relationship. In the above example, we don't pass the parameter

docs/ref/signals.txt

@@ -30,6 +30,10 @@ module system.
     If you override these methods on your model, you must call the parent class'
     methods for this signals to be sent.
 
+	Note also that Django stores signal handlers as weak references by default,
+	so if your handler is a local function, it may be garbage collected.  To
+	prevent this, pass ``weak=False`` when you call the signal's :meth:`~django.dispatch.Signal.connect`.
+
 pre_init
 --------
 

docs/topics/auth.txt

@@ -463,6 +463,12 @@ When a user profile model has been defined and specified in this manner, each
 instance of the user profile model associated with that
 :class:`~django.contrib.auth.models.User`.
 
+The method :class:`~django.contrib.auth.models.User.get_profile()`
+does not create the profile, if it does not exist. You need to
+register a handler for the signal
+:attr:`django.db.models.signals.post_save` on the User model, and, in
+the handler, if created=True, create the associated user profile.
+
 For more information, see `Chapter 12 of the Django book`_.
 
 .. _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::
         <p>Your username and password didn't match. Please try again.</p>
         {% endif %}
 
-        <form method="post" action="">
+        <form method="post" action="{% url django.contrib.auth.views.login %}">
         <table>
         <tr>
             <td>{{ form.username.label_tag }}</td>
@@ -868,6 +874,34 @@ includes a few other useful built-in views located in
         * ``login_url``: The URL of the login page to redirect to. This will
           default to :setting:`settings.LOGIN_URL <LOGIN_URL>` if not supplied.
 
+.. function:: password_reset_confirm(request[,uidb36, token, template_name, token_generator, set_password_form, post_reset_redirect])
+
+    Presents a form for entering a new password.
+
+    **Optional arguments:**
+
+        * ``uidb36``: The user's id encoded in base 36. This will default to
+          ``None``.
+        * ``token``: Token to check that the password is valid. This will default to ``None``.
+        * ``template_name``: The full name of a template to display the confirm
+          password view. Default value is :file:`registration/password_reset_confirm.html`.
+        * ``token_generator``: Instance of the class to check the password. This
+          will default to ``default_token_generator``, it's an instance of
+          ``django.contrib.auth.tokens.PasswordResetTokenGenerator``.
+        * ``set_password_form``: Form that will use to set the password. This will 
+          default to ``SetPasswordForm``.
+        * ``post_reset_redirect``: URL to redirect after the password reset
+          done. This will default to ``None``.
+
+.. function:: password_reset_complete(request[,template_name])
+
+   Presents a view that informs that the password has been changed very well.
+
+   **Optional arguments:** 
+
+       * ``template_name``: The full name of a template to display the view.
+         This will default to :file:`registration/password_reset_complete.html`.
+
 Built-in forms
 --------------
 
@@ -1125,10 +1159,10 @@ The currently logged-in user and his/her permissions are made available in the
 Users
 -----
 
-The currently logged-in user, either a
+When rendering a template :class:`~django.template.context.RequestContext`, the
-:class:`~django.contrib.auth.models.User` instance or an
+currently logged-in user, either a  :class:`~django.contrib.auth.models.User`
-:class:`~django.contrib.auth.models.AnonymousUser` instance, is stored in the
+instance or an :class:`~django.contrib.auth.models.AnonymousUser` instance, is
-template variable ``{{ user }}``:
+stored in the template variable ``{{ user }}``:
 
 .. code-block:: html
 
@@ -1138,6 +1172,9 @@ template variable ``{{ user }}``:
         <p>Welcome, new user. Please log in.</p>
     {% endif %}
 
+This template context variable is not available if a ``RequestContext`` is not
+being used.
+
 Permissions
 -----------
 

docs/topics/http/shortcuts.txt

@@ -19,7 +19,7 @@ Required arguments
 ------------------
 
 ``template``
-    The full name of a template to use.
+    The full name of a template to use or sequence of template names.
 
 Optional arguments
 ------------------

docs/topics/http/urls.txt

@@ -633,6 +633,40 @@ reverse such patterns.
     be imported correctly. Do not include lines that reference views you
     haven't written yet, because those views will not be importable.
 
+resolve()
+---------
+
+The :func:`django.core.urlresolvers.resolve` function can be used for resolving
+URL paths to the corresponding view functions. It has the following signature:
+
+.. currentmodule:: django.core.urlresolvers
+.. function:: resolve(path, urlconf=None)
+
+``path`` is the URL path you want to resolve. As with ``reverse()`` above, you
+don't need to worry about the ``urlconf`` parameter. The function returns the
+triple (view function, arguments, keyword arguments).
+
+For example, it can be used for testing if a view would raise a ``Http404``
+error before redirecting to it::
+
+    from urlparse import urlparse
+    from django.core.urlresolvers import resolve
+    from django.http import HttpResponseRedirect, Http404
+
+    def myview(request):
+        next = request.META.get('HTTP_REFERER', None) or '/'
+        response = HttpResponseRedirect(next)
+
+        # modify the request and response as required, e.g. change locale
+        # and set corresponding locale cookie
+
+        view, args, kwargs = resolve(urlparse(next)[2])
+        kwargs['request'] = request
+        try:
+            view(*args, **kwargs)
+        except Http404:
+            return HttpResponseRedirect('/')
+        return response
 
 permalink()
 -----------

docs/topics/testing.txt

@@ -138,10 +138,11 @@ and execute those lines while checking that the results match.
 In the case of model tests, note that the test runner takes care of creating
 its own test database. That is, any test that accesses a database -- by
 creating and saving model instances, for example -- will not affect your
-production database. Each doctest begins with a "blank slate" -- a fresh
+production database. However, the database is not refreshed between doctests,
-database containing an empty table for each model. (See the section on
+so if your doctest requires a certain state you should consider flushin the 
-fixtures, below, for more on this.) Note that to use this feature, the database
+database or loading a fixture. (See the section on fixtures, below, for more 
-user Django is connecting as must have ``CREATE DATABASE`` rights.
+on this.) Note that to use this feature, the database user Django is connecting
+as must have ``CREATE DATABASE`` rights.
 
 For more details about how doctest works, see the `standard library
 documentation for doctest`_.