Browse files

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

…#9343, #9529,

git-svn-id: bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
1 parent 15becf2 commit 516051bfd2b537f441c46359cce7eacbf15fc4b8 @jacobian jacobian committed Mar 31, 2009
@@ -242,6 +242,7 @@ answer newbie questions, and generally made Django that much better:
knox <>
David Krauth
+ Kevin Kubasik <>
Denis Kuzmichyov <>
Panos Laganakos <>
@@ -70,6 +70,11 @@
# 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
# -----------------------
@@ -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`.
@@ -13,8 +13,8 @@ Glossary
See :ref:`topics-db-models`.
generic view
- A higher-order :term:`view` function that abstracts common idioms and patterns
- found in view development and abstracts them.
+ A higher-order :term:`view` function that provides an abstract/generic
+ 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.
- A chunk of text that separates the presentation of a document from its
- data.
+ A chunk of text that acts as formatting for representing data. A
+ template helps to abstract the presentation of data from the data
+ itself.
See :ref:`topics-templates`.
@@ -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:
Running Django on a shared-hosting provider with Apache
@@ -13,6 +13,7 @@ ways to easily deploy Django:
+ modwsgi
If you're new to deploying Django and/or Python, we'd recommend you try
@@ -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:
+.. _Nginx:
.. _TUX:
.. _Apache:
+.. _Cherokee:
.. _howto-deployment-modpython-serving-the-admin-files:
@@ -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
@@ -19,6 +19,7 @@ use the :func:`django.views.static.serve` view to serve media files.
.. _Apache:
.. _lighttpd:
+.. _Cherokee:
The big, fat disclaimer
@@ -72,6 +73,9 @@ required. For example, if we have a line in ```` 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
@@ -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 ````,
-the URLconf will look for ``/myapp/``. In a request to
-````, the URLconf will look for ``/myapp/``.
+the URLconf will look for ``myapp/``. In a request to
+````, 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"
@@ -832,8 +832,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
-specifying them in a ``ModelAdmin.inlines`` attribute::
+parent model. These are called inlines. Suppose you have these two models::
+ 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
@@ -1165,7 +1174,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
```` at the URL ``/admin/`` ::
@@ -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">
- <input type="submit" name="preview" class="submit-post" value="Preview">
- </p>
+ <tr>
+ <td></td>
+ <td><input type="submit" name="preview" class="submit-post" value="Preview"></td>
+ </tr>
Be sure to read the `notes on the comment form`_, below, for some special
@@ -324,6 +324,14 @@ same types of lookups manually::
[<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
+ 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`
@@ -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
@@ -87,8 +87,8 @@ MySQL notes
Django expects the database to support transactions, referential integrity,
-and Unicode (UTF-8 encoding). Fortunately, MySQL_ has all these
-features available as far back as 3.23. While it may be possible to use
+and Unicode support (UTF-8 encoding). Fortunately, MySQL_ has all these
+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
@@ -341,6 +341,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
@@ -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(
+ >>> 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.
@@ -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
Avoid using :attr:`~Field.null` on string-based fields such as
-:class:`~django.db.models.CharField` and :class:`~django.db.models.TextField`
-unless you have an excellent reason. If a string-based field has ``null=True``,
-that means it has two possible values for "no data": ``NULL``, and the empty
-string. In most cases, it's redundant to have two possible values for "no
-data;" Django convention is to use the empty string, not ``NULL``.
+:class:`CharField` and :class:`TextField` unless you have an excellent reason.
+If a string-based field has ``null=True``, that means it has two possible values
+for "no data": ``NULL``, and the empty string. In most cases, it's redundant to
+have two possible values for "no data;" Django convention is to use the empty
+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`.
-:attr:`~Field.choices` is meant for static data that doesn't change much, if
+proper database table with a :class:`ForeignKey`. :attr:`~Field.choices` is
+meant for static data that doesn't change much, if ever.
@@ -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
-primary key, so you don't need to set ``primary_key=True`` on any of your
-fields unless you want to override the default primary-key behavior. For more,
-see :ref:`automatic-primary-key-fields`.
+will automatically add an :class:`IntegerField` to hold the primary key, so you
+don't need to set ``primary_key=True`` on any of your fields unless you want to
+override the default primary-key behavior. For more, see
``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:`` method.
-This option is valid on all field types except
-:class:`~django.db.models.ManyToManyField` and
+This option is valid on all field types except :class:`ManyToManyField` and
.. attribute:: Field.unique_for_date
-Set this to the name of a :class:`~django.db.models.DateField` or
-:class:`~django.db.models.DateTimeField` to require that this field be unique
-for the value of the date field.
+Set this to the name of a :class:`DateField` or :class:`DateTimeField` to
+require that this field be unique 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).
@@ -154,7 +154,7 @@ In SQL terms, that evaluates to::
WHERE NOT pub_date > '2005-1-3'
- AND NOT headline = 'Hello'
+ OR NOT headline = 'Hello'
Note the second example is more restrictive.
@@ -1484,8 +1484,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.
+ 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. <>`_
@@ -42,7 +42,7 @@ Extra methods on managers when used in a ForeignKey context
.... body_text='Hi',
...., 1, 1)
.... )
- >>>
+ >>>
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
@@ -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`.
Oops, something went wrong.

0 comments on commit 516051b

Please sign in to comment.