Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Removed use of non-standard indentation rules in docs, and the custom…

… transform that supported them.

Doc writers should be aware that we are now back to normal ReST rules
regarding blockquotes.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@16955 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit c61987d75ad9bc5233257f46a8246bb9d63bbbe1 1 parent af244e4
Luke Plant authored October 10, 2011
22  docs/_ext/djangodocs.py
@@ -62,7 +62,6 @@ def setup(app):
62 62
     app.add_config_value('django_next_version', '0.0', True)
63 63
     app.add_directive('versionadded', VersionDirective)
64 64
     app.add_directive('versionchanged', VersionDirective)
65  
-    app.add_transform(SuppressBlockquotes)
66 65
     app.add_builder(DjangoStandaloneHTMLBuilder)
67 66
 
68 67
 
@@ -99,27 +98,6 @@ def run(self):
99 98
         return ret
100 99
 
101 100
 
102  
-class SuppressBlockquotes(transforms.Transform):
103  
-    """
104  
-    Remove the default blockquotes that encase indented list, tables, etc.
105  
-    """
106  
-    default_priority = 300
107  
-
108  
-    suppress_blockquote_child_nodes = (
109  
-        nodes.bullet_list,
110  
-        nodes.enumerated_list,
111  
-        nodes.definition_list,
112  
-        nodes.literal_block,
113  
-        nodes.doctest_block,
114  
-        nodes.line_block,
115  
-        nodes.table
116  
-    )
117  
-
118  
-    def apply(self):
119  
-        for node in self.document.traverse(nodes.block_quote):
120  
-            if len(node.children) == 1 and isinstance(node.children[0], self.suppress_blockquote_child_nodes):
121  
-                node.replace_self(node.children[0])
122  
-
123 101
 class DjangoHTMLTranslator(SmartyPantsHTMLTranslator):
124 102
     """
125 103
     Django-specific reST to HTML tweaks.
582  docs/ref/contrib/admin/index.txt
@@ -16,31 +16,31 @@ Overview
16 16
 
17 17
 There are seven steps in activating the Django admin site:
18 18
 
19  
-    1. Add ``'django.contrib.admin'`` to your :setting:`INSTALLED_APPS`
20  
-       setting.
  19
+1. Add ``'django.contrib.admin'`` to your :setting:`INSTALLED_APPS`
  20
+   setting.
21 21
 
22  
-    2. The admin has four dependencies - :mod:`django.contrib.auth`,
23  
-       :mod:`django.contrib.contenttypes`,
24  
-       :mod:`django.contrib.messages` and
25  
-       :mod:`django.contrib.sessions`.  If these applications are not
26  
-       in your :setting:`INSTALLED_APPS` list, add them.
  22
+2. The admin has four dependencies - :mod:`django.contrib.auth`,
  23
+   :mod:`django.contrib.contenttypes`,
  24
+   :mod:`django.contrib.messages` and
  25
+   :mod:`django.contrib.sessions`.  If these applications are not
  26
+   in your :setting:`INSTALLED_APPS` list, add them.
27 27
 
28  
-    3. Add ``django.contrib.messages.context_processors.messages`` to
29  
-       :setting:`TEMPLATE_CONTEXT_PROCESSORS` and
30  
-       :class:`~django.contrib.messages.middleware.MessageMiddleware` to
31  
-       :setting:`MIDDLEWARE_CLASSES`.
  28
+3. Add ``django.contrib.messages.context_processors.messages`` to
  29
+   :setting:`TEMPLATE_CONTEXT_PROCESSORS` and
  30
+   :class:`~django.contrib.messages.middleware.MessageMiddleware` to
  31
+   :setting:`MIDDLEWARE_CLASSES`.
32 32
 
33  
-    4. Determine which of your application's models should be editable in the
34  
-       admin interface.
  33
+4. Determine which of your application's models should be editable in the
  34
+   admin interface.
35 35
 
36  
-    5. For each of those models, optionally create a ``ModelAdmin`` class that
37  
-       encapsulates the customized admin functionality and options for that
38  
-       particular model.
  36
+5. For each of those models, optionally create a ``ModelAdmin`` class that
  37
+   encapsulates the customized admin functionality and options for that
  38
+   particular model.
39 39
 
40  
-    6. Instantiate an ``AdminSite`` and tell it about each of your models and
41  
-       ``ModelAdmin`` classes.
  40
+6. Instantiate an ``AdminSite`` and tell it about each of your models and
  41
+   ``ModelAdmin`` classes.
42 42
 
43  
-    7. Hook the ``AdminSite`` instance into your URLconf.
  43
+7. Hook the ``AdminSite`` instance into your URLconf.
44 44
 
45 45
 Other topics
46 46
 ------------
@@ -239,54 +239,54 @@ subclass::
239 239
 
240 240
     The ``field_options`` dictionary can have the following keys:
241 241
 
242  
-        * ``fields``
243  
-            A tuple of field names to display in this fieldset. This key is
244  
-            required.
  242
+    * ``fields``
  243
+        A tuple of field names to display in this fieldset. This key is
  244
+        required.
245 245
 
246  
-            Example::
  246
+        Example::
247 247
 
248  
-                {
249  
-                'fields': ('first_name', 'last_name', 'address', 'city', 'state'),
250  
-                }
  248
+            {
  249
+            'fields': ('first_name', 'last_name', 'address', 'city', 'state'),
  250
+            }
251 251
 
252  
-            Just like with the :attr:`~ModelAdmin.fields` option, to display
253  
-            multiple fields on the same line, wrap those fields in their own
254  
-            tuple. In this example, the ``first_name`` and ``last_name`` fields
255  
-            will display on the same line::
  252
+        Just like with the :attr:`~ModelAdmin.fields` option, to display
  253
+        multiple fields on the same line, wrap those fields in their own
  254
+        tuple. In this example, the ``first_name`` and ``last_name`` fields
  255
+        will display on the same line::
256 256
 
257  
-                {
258  
-                'fields': (('first_name', 'last_name'), 'address', 'city', 'state'),
259  
-                }
  257
+            {
  258
+            'fields': (('first_name', 'last_name'), 'address', 'city', 'state'),
  259
+            }
260 260
 
261  
-            .. versionadded:: 1.2
  261
+        .. versionadded:: 1.2
262 262
 
263  
-            ``fields`` can contain values defined in
264  
-            :attr:`~ModelAdmin.readonly_fields` to be displayed as read-only.
  263
+        ``fields`` can contain values defined in
  264
+        :attr:`~ModelAdmin.readonly_fields` to be displayed as read-only.
265 265
 
266  
-        * ``classes``
267  
-            A list containing extra CSS classes to apply to the fieldset.
  266
+    * ``classes``
  267
+        A list containing extra CSS classes to apply to the fieldset.
268 268
 
269  
-            Example::
  269
+        Example::
270 270
 
271  
-                {
272  
-                'classes': ['wide', 'extrapretty'],
273  
-                }
  271
+            {
  272
+            'classes': ['wide', 'extrapretty'],
  273
+            }
274 274
 
275  
-            Two useful classes defined by the default admin site stylesheet are
276  
-            ``collapse`` and ``wide``. Fieldsets with the ``collapse`` style
277  
-            will be initially collapsed in the admin and replaced with a small
278  
-            "click to expand" link. Fieldsets with the ``wide`` style will be
279  
-            given extra horizontal space.
  275
+        Two useful classes defined by the default admin site stylesheet are
  276
+        ``collapse`` and ``wide``. Fieldsets with the ``collapse`` style
  277
+        will be initially collapsed in the admin and replaced with a small
  278
+        "click to expand" link. Fieldsets with the ``wide`` style will be
  279
+        given extra horizontal space.
280 280
 
281  
-        * ``description``
282  
-            A string of optional extra text to be displayed at the top of each
283  
-            fieldset, under the heading of the fieldset.
  281
+    * ``description``
  282
+        A string of optional extra text to be displayed at the top of each
  283
+        fieldset, under the heading of the fieldset.
284 284
 
285  
-            Note that this value is *not* HTML-escaped when it's displayed in
286  
-            the admin interface. This lets you include HTML if you so desire.
287  
-            Alternatively you can use plain text and
288  
-            ``django.utils.html.escape()`` to escape any HTML special
289  
-            characters.
  285
+        Note that this value is *not* HTML-escaped when it's displayed in
  286
+        the admin interface. This lets you include HTML if you so desire.
  287
+        Alternatively you can use plain text and
  288
+        ``django.utils.html.escape()`` to escape any HTML special
  289
+        characters.
290 290
 
291 291
 .. attribute:: ModelAdmin.filter_horizontal
292 292
 
@@ -400,129 +400,129 @@ subclass::
400 400
 
401 401
     You have four possible values that can be used in ``list_display``:
402 402
 
403  
-        * A field of the model. For example::
  403
+    * A field of the model. For example::
404 404
 
405  
-              class PersonAdmin(admin.ModelAdmin):
406  
-                  list_display = ('first_name', 'last_name')
  405
+          class PersonAdmin(admin.ModelAdmin):
  406
+              list_display = ('first_name', 'last_name')
407 407
 
408  
-        * A callable that accepts one parameter for the model instance. For
409  
-          example::
  408
+    * A callable that accepts one parameter for the model instance. For
  409
+      example::
410 410
 
411  
-              def upper_case_name(obj):
412  
-                  return ("%s %s" % (obj.first_name, obj.last_name)).upper()
413  
-              upper_case_name.short_description = 'Name'
  411
+          def upper_case_name(obj):
  412
+              return ("%s %s" % (obj.first_name, obj.last_name)).upper()
  413
+          upper_case_name.short_description = 'Name'
414 414
 
415  
-              class PersonAdmin(admin.ModelAdmin):
416  
-                  list_display = (upper_case_name,)
  415
+          class PersonAdmin(admin.ModelAdmin):
  416
+              list_display = (upper_case_name,)
417 417
 
418  
-        * A string representing an attribute on the ``ModelAdmin``. This
419  
-          behaves same as the callable. For example::
  418
+    * A string representing an attribute on the ``ModelAdmin``. This
  419
+      behaves same as the callable. For example::
420 420
 
421  
-              class PersonAdmin(admin.ModelAdmin):
422  
-                  list_display = ('upper_case_name',)
  421
+          class PersonAdmin(admin.ModelAdmin):
  422
+              list_display = ('upper_case_name',)
423 423
 
424  
-                  def upper_case_name(self, obj):
425  
-                    return ("%s %s" % (obj.first_name, obj.last_name)).upper()
426  
-                  upper_case_name.short_description = 'Name'
  424
+              def upper_case_name(self, obj):
  425
+                return ("%s %s" % (obj.first_name, obj.last_name)).upper()
  426
+              upper_case_name.short_description = 'Name'
427 427
 
428  
-        * A string representing an attribute on the model. This behaves almost
429  
-          the same as the callable, but ``self`` in this context is the model
430  
-          instance. Here's a full model example::
  428
+    * A string representing an attribute on the model. This behaves almost
  429
+      the same as the callable, but ``self`` in this context is the model
  430
+      instance. Here's a full model example::
431 431
 
432  
-              class Person(models.Model):
433  
-                  name = models.CharField(max_length=50)
434  
-                  birthday = models.DateField()
  432
+          class Person(models.Model):
  433
+              name = models.CharField(max_length=50)
  434
+              birthday = models.DateField()
435 435
 
436  
-                  def decade_born_in(self):
437  
-                      return self.birthday.strftime('%Y')[:3] + "0's"
438  
-                  decade_born_in.short_description = 'Birth decade'
  436
+              def decade_born_in(self):
  437
+                  return self.birthday.strftime('%Y')[:3] + "0's"
  438
+              decade_born_in.short_description = 'Birth decade'
439 439
 
440  
-              class PersonAdmin(admin.ModelAdmin):
441  
-                  list_display = ('name', 'decade_born_in')
  440
+          class PersonAdmin(admin.ModelAdmin):
  441
+              list_display = ('name', 'decade_born_in')
442 442
 
443 443
     A few special cases to note about ``list_display``:
444 444
 
445  
-        * If the field is a ``ForeignKey``, Django will display the
446  
-          ``__unicode__()`` of the related object.
  445
+    * If the field is a ``ForeignKey``, Django will display the
  446
+      ``__unicode__()`` of the related object.
447 447
 
448  
-        * ``ManyToManyField`` fields aren't supported, because that would
449  
-          entail executing a separate SQL statement for each row in the table.
450  
-          If you want to do this nonetheless, give your model a custom method,
451  
-          and add that method's name to ``list_display``. (See below for more
452  
-          on custom methods in ``list_display``.)
  448
+    * ``ManyToManyField`` fields aren't supported, because that would
  449
+      entail executing a separate SQL statement for each row in the table.
  450
+      If you want to do this nonetheless, give your model a custom method,
  451
+      and add that method's name to ``list_display``. (See below for more
  452
+      on custom methods in ``list_display``.)
453 453
 
454  
-        * If the field is a ``BooleanField`` or ``NullBooleanField``, Django
455  
-          will display a pretty "on" or "off" icon instead of ``True`` or
456  
-          ``False``.
  454
+    * If the field is a ``BooleanField`` or ``NullBooleanField``, Django
  455
+      will display a pretty "on" or "off" icon instead of ``True`` or
  456
+      ``False``.
457 457
 
458  
-        * If the string given is a method of the model, ``ModelAdmin`` or a
459  
-          callable, Django will HTML-escape the output by default. If you'd
460  
-          rather not escape the output of the method, give the method an
461  
-          ``allow_tags`` attribute whose value is ``True``.
  458
+    * If the string given is a method of the model, ``ModelAdmin`` or a
  459
+      callable, Django will HTML-escape the output by default. If you'd
  460
+      rather not escape the output of the method, give the method an
  461
+      ``allow_tags`` attribute whose value is ``True``.
462 462
 
463  
-          Here's a full example model::
  463
+      Here's a full example model::
464 464
 
465  
-              class Person(models.Model):
466  
-                  first_name = models.CharField(max_length=50)
467  
-                  last_name = models.CharField(max_length=50)
468  
-                  color_code = models.CharField(max_length=6)
  465
+          class Person(models.Model):
  466
+              first_name = models.CharField(max_length=50)
  467
+              last_name = models.CharField(max_length=50)
  468
+              color_code = models.CharField(max_length=6)
469 469
 
470  
-                  def colored_name(self):
471  
-                      return '<span style="color: #%s;">%s %s</span>' % (self.color_code, self.first_name, self.last_name)
472  
-                  colored_name.allow_tags = True
  470
+              def colored_name(self):
  471
+                  return '<span style="color: #%s;">%s %s</span>' % (self.color_code, self.first_name, self.last_name)
  472
+              colored_name.allow_tags = True
473 473
 
474  
-              class PersonAdmin(admin.ModelAdmin):
475  
-                  list_display = ('first_name', 'last_name', 'colored_name')
  474
+          class PersonAdmin(admin.ModelAdmin):
  475
+              list_display = ('first_name', 'last_name', 'colored_name')
476 476
 
477  
-        * If the string given is a method of the model, ``ModelAdmin`` or a
478  
-          callable that returns True or False Django will display a pretty
479  
-          "on" or "off" icon if you give the method a ``boolean`` attribute
480  
-          whose value is ``True``.
  477
+    * If the string given is a method of the model, ``ModelAdmin`` or a
  478
+      callable that returns True or False Django will display a pretty
  479
+      "on" or "off" icon if you give the method a ``boolean`` attribute
  480
+      whose value is ``True``.
481 481
 
482  
-          Here's a full example model::
  482
+      Here's a full example model::
483 483
 
484  
-              class Person(models.Model):
485  
-                  first_name = models.CharField(max_length=50)
486  
-                  birthday = models.DateField()
  484
+          class Person(models.Model):
  485
+              first_name = models.CharField(max_length=50)
  486
+              birthday = models.DateField()
487 487
 
488  
-                  def born_in_fifties(self):
489  
-                      return self.birthday.strftime('%Y')[:3] == '195'
490  
-                  born_in_fifties.boolean = True
  488
+              def born_in_fifties(self):
  489
+                  return self.birthday.strftime('%Y')[:3] == '195'
  490
+              born_in_fifties.boolean = True
491 491
 
492  
-              class PersonAdmin(admin.ModelAdmin):
493  
-                  list_display = ('name', 'born_in_fifties')
  492
+          class PersonAdmin(admin.ModelAdmin):
  493
+              list_display = ('name', 'born_in_fifties')
494 494
 
495 495
 
496  
-        * The ``__str__()`` and ``__unicode__()`` methods are just as valid in
497  
-          ``list_display`` as any other model method, so it's perfectly OK to
498  
-          do this::
  496
+    * The ``__str__()`` and ``__unicode__()`` methods are just as valid in
  497
+      ``list_display`` as any other model method, so it's perfectly OK to
  498
+      do this::
499 499
 
500  
-              list_display = ('__unicode__', 'some_other_field')
  500
+          list_display = ('__unicode__', 'some_other_field')
501 501
 
502  
-        * Usually, elements of ``list_display`` that aren't actual database
503  
-          fields can't be used in sorting (because Django does all the sorting
504  
-          at the database level).
  502
+    * Usually, elements of ``list_display`` that aren't actual database
  503
+      fields can't be used in sorting (because Django does all the sorting
  504
+      at the database level).
505 505
 
506  
-          However, if an element of ``list_display`` represents a certain
507  
-          database field, you can indicate this fact by setting the
508  
-          ``admin_order_field`` attribute of the item.
  506
+      However, if an element of ``list_display`` represents a certain
  507
+      database field, you can indicate this fact by setting the
  508
+      ``admin_order_field`` attribute of the item.
509 509
 
510  
-          For example::
  510
+      For example::
511 511
 
512  
-            class Person(models.Model):
513  
-                first_name = models.CharField(max_length=50)
514  
-                color_code = models.CharField(max_length=6)
  512
+        class Person(models.Model):
  513
+            first_name = models.CharField(max_length=50)
  514
+            color_code = models.CharField(max_length=6)
515 515
 
516  
-                def colored_first_name(self):
517  
-                    return '<span style="color: #%s;">%s</span>' % (self.color_code, self.first_name)
518  
-                colored_first_name.allow_tags = True
519  
-                colored_first_name.admin_order_field = 'first_name'
  516
+            def colored_first_name(self):
  517
+                return '<span style="color: #%s;">%s</span>' % (self.color_code, self.first_name)
  518
+            colored_first_name.allow_tags = True
  519
+            colored_first_name.admin_order_field = 'first_name'
520 520
 
521  
-            class PersonAdmin(admin.ModelAdmin):
522  
-                list_display = ('first_name', 'colored_first_name')
  521
+        class PersonAdmin(admin.ModelAdmin):
  522
+            list_display = ('first_name', 'colored_first_name')
523 523
 
524  
-          The above will tell Django to order by the ``first_name`` field when
525  
-          trying to sort by ``colored_first_name`` in the admin.
  524
+      The above will tell Django to order by the ``first_name`` field when
  525
+      trying to sort by ``colored_first_name`` in the admin.
526 526
 
527 527
 .. attribute:: ModelAdmin.list_display_links
528 528
 
@@ -561,12 +561,12 @@ subclass::
561 561
         ``list_editable`` interacts with a couple of other options in
562 562
         particular ways; you should note the following rules:
563 563
 
564  
-            * Any field in ``list_editable`` must also be in ``list_display``.
565  
-              You can't edit a field that's not displayed!
  564
+        * Any field in ``list_editable`` must also be in ``list_display``.
  565
+          You can't edit a field that's not displayed!
566 566
 
567  
-            * The same field can't be listed in both ``list_editable`` and
568  
-              ``list_display_links`` -- a field can't be both a form and
569  
-              a link.
  567
+        * The same field can't be listed in both ``list_editable`` and
  568
+          ``list_display_links`` -- a field can't be both a form and
  569
+          a link.
570 570
 
571 571
         You'll get a validation error if either of these rules are broken.
572 572
 
@@ -582,119 +582,119 @@ subclass::
582 582
     ``list_filter`` should be a list of elements, where each element should be
583 583
     of one of the following types:
584 584
 
585  
-        * a field name, where the specified field should be either a
586  
-          ``BooleanField``, ``CharField``, ``DateField``, ``DateTimeField``,
587  
-          ``IntegerField``, ``ForeignKey`` or ``ManyToManyField``, for example::
588  
-
589  
-              class PersonAdmin(ModelAdmin):
590  
-                  list_filter = ('is_staff', 'company')
591  
-
592  
-          .. versionadded:: 1.3
593  
-
594  
-          Field names in ``list_filter`` can also span relations
595  
-          using the ``__`` lookup, for example::
596  
-
597  
-              class PersonAdmin(UserAdmin):
598  
-                  list_filter = ('company__name',)
599  
-
600  
-        * a class inheriting from :mod:`django.contrib.admin.SimpleListFilter`,
601  
-          which you need to provide the ``title`` and ``parameter_name``
602  
-          attributes to and override the ``lookups`` and ``queryset`` methods,
603  
-          e.g.::
604  
-
605  
-               from django.utils.translation import ugettext_lazy as _
606  
-               from django.contrib.admin import SimpleListFilter
607  
-
608  
-               class DecadeBornListFilter(SimpleListFilter):
609  
-                   # Human-readable title which will be displayed in the
610  
-                   # right admin sidebar just above the filter options.
611  
-                   title = _('decade born')
612  
-
613  
-                   # Parameter for the filter that will be used in the URL query.
614  
-                   parameter_name = 'decade'
615  
-
616  
-                   def lookups(self, request, model_admin):
617  
-                       """
618  
-                       Returns a list of tuples. The first element in each
619  
-                       tuple is the coded value for the option that will
620  
-                       appear in the URL query. The second element is the
621  
-                       human-readable name for the option that will appear
622  
-                       in the right sidebar.
623  
-                       """
624  
-                       return (
625  
-                           ('80s', _('in the eighties')),
626  
-                           ('90s', _('in the nineties')),
627  
-                       )
628  
-
629  
-                   def queryset(self, request, queryset):
630  
-                       """
631  
-                       Returns the filtered queryset based on the value
632  
-                       provided in the query string and retrievable via
633  
-                       `self.value()`.
634  
-                       """
635  
-                       # Compare the requested value (either '80s' or 'other')
636  
-                       # to decide how to filter the queryset.
637  
-                       if self.value() == '80s':
638  
-                           return queryset.filter(birthday__year__gte=1980,
639  
-                                                   birthday__year__lte=1989)
640  
-                       if self.value() == '90s':
641  
-                           return queryset.filter(birthday__year__gte=1990,
642  
-                                                  birthday__year__lte=1999)
643  
-
644  
-               class PersonAdmin(ModelAdmin):
645  
-                   list_filter = (DecadeBornListFilter,)
646  
-
647  
-          .. note::
648  
-
649  
-              As a convenience, the ``HttpRequest`` object is passed to the
650  
-              ``lookups`` and ``queryset`` methods, for example::
651  
-
652  
-                  class AuthDecadeBornListFilter(DecadeBornListFilter):
653  
-
654  
-                      def lookups(self, request, model_admin):
655  
-                          if request.user.is_superuser:
656  
-                              return super(AuthDecadeBornListFilter,
657  
-                                  self).lookups(request, model_admin)
658  
-
659  
-                      def queryset(self, request, queryset):
660  
-                          if request.user.is_superuser:
661  
-                              return super(AuthDecadeBornListFilter,
662  
-                                  self).queryset(request, queryset)
663  
-
664  
-              Also as a convenience, the ``ModelAdmin`` object is passed to
665  
-              the ``lookups`` method, for example if you want to base the
666  
-              lookups on the available data::
667  
-
668  
-                  class AdvancedDecadeBornListFilter(DecadeBornListFilter):
669  
-
670  
-                      def lookups(self, request, model_admin):
671  
-                          """
672  
-                          Only show the lookups if there actually is
673  
-                          anyone born in the corresponding decades.
674  
-                          """
675  
-                          qs = model_admin.queryset(request)
676  
-                          if qs.filter(birthday__year__gte=1980,
677  
-                                        birthday__year__lte=1989).exists():
678  
-                              yield ('80s', _('in the eighties'))
679  
-                          if qs.filter(birthday__year__gte=1990,
680  
-                                        birthday__year__lte=1999).exists():
681  
-                              yield ('90s', _('in the nineties'))
682  
-
683  
-        * a tuple, where the first element is a field name and the second
684  
-          element is a class inheriting from
685  
-          :mod:`django.contrib.admin.FieldListFilter`, for example::
686  
-
687  
-              from django.contrib.admin import BooleanFieldListFilter
688  
-
689  
-              class PersonAdmin(ModelAdmin):
690  
-                  list_filter = (
691  
-                      ('is_staff', BooleanFieldListFilter),
692  
-                  )
693  
-
694  
-          .. note::
695  
-
696  
-              The ``FieldListFilter`` API is currently considered internal
697  
-              and prone to refactoring.
  585
+    * a field name, where the specified field should be either a
  586
+      ``BooleanField``, ``CharField``, ``DateField``, ``DateTimeField``,
  587
+      ``IntegerField``, ``ForeignKey`` or ``ManyToManyField``, for example::
  588
+
  589
+          class PersonAdmin(ModelAdmin):
  590
+              list_filter = ('is_staff', 'company')
  591
+
  592
+      .. versionadded:: 1.3
  593
+
  594
+      Field names in ``list_filter`` can also span relations
  595
+      using the ``__`` lookup, for example::
  596
+
  597
+          class PersonAdmin(UserAdmin):
  598
+              list_filter = ('company__name',)
  599
+
  600
+    * a class inheriting from :mod:`django.contrib.admin.SimpleListFilter`,
  601
+      which you need to provide the ``title`` and ``parameter_name``
  602
+      attributes to and override the ``lookups`` and ``queryset`` methods,
  603
+      e.g.::
  604
+
  605
+           from django.utils.translation import ugettext_lazy as _
  606
+           from django.contrib.admin import SimpleListFilter
  607
+
  608
+           class DecadeBornListFilter(SimpleListFilter):
  609
+               # Human-readable title which will be displayed in the
  610
+               # right admin sidebar just above the filter options.
  611
+               title = _('decade born')
  612
+
  613
+               # Parameter for the filter that will be used in the URL query.
  614
+               parameter_name = 'decade'
  615
+
  616
+               def lookups(self, request, model_admin):
  617
+                   """
  618
+                   Returns a list of tuples. The first element in each
  619
+                   tuple is the coded value for the option that will
  620
+                   appear in the URL query. The second element is the
  621
+                   human-readable name for the option that will appear
  622
+                   in the right sidebar.
  623
+                   """
  624
+                   return (
  625
+                       ('80s', _('in the eighties')),
  626
+                       ('90s', _('in the nineties')),
  627
+                   )
  628
+
  629
+               def queryset(self, request, queryset):
  630
+                   """
  631
+                   Returns the filtered queryset based on the value
  632
+                   provided in the query string and retrievable via
  633
+                   `self.value()`.
  634
+                   """
  635
+                   # Compare the requested value (either '80s' or 'other')
  636
+                   # to decide how to filter the queryset.
  637
+                   if self.value() == '80s':
  638
+                       return queryset.filter(birthday__year__gte=1980,
  639
+                                               birthday__year__lte=1989)
  640
+                   if self.value() == '90s':
  641
+                       return queryset.filter(birthday__year__gte=1990,
  642
+                                              birthday__year__lte=1999)
  643
+
  644
+           class PersonAdmin(ModelAdmin):
  645
+               list_filter = (DecadeBornListFilter,)
  646
+
  647
+      .. note::
  648
+
  649
+          As a convenience, the ``HttpRequest`` object is passed to the
  650
+          ``lookups`` and ``queryset`` methods, for example::
  651
+
  652
+              class AuthDecadeBornListFilter(DecadeBornListFilter):
  653
+
  654
+                  def lookups(self, request, model_admin):
  655
+                      if request.user.is_superuser:
  656
+                          return super(AuthDecadeBornListFilter,
  657
+                              self).lookups(request, model_admin)
  658
+
  659
+                  def queryset(self, request, queryset):
  660
+                      if request.user.is_superuser:
  661
+                          return super(AuthDecadeBornListFilter,
  662
+                              self).queryset(request, queryset)
  663
+
  664
+          Also as a convenience, the ``ModelAdmin`` object is passed to
  665
+          the ``lookups`` method, for example if you want to base the
  666
+          lookups on the available data::
  667
+
  668
+              class AdvancedDecadeBornListFilter(DecadeBornListFilter):
  669
+
  670
+                  def lookups(self, request, model_admin):
  671
+                      """
  672
+                      Only show the lookups if there actually is
  673
+                      anyone born in the corresponding decades.
  674
+                      """
  675
+                      qs = model_admin.queryset(request)
  676
+                      if qs.filter(birthday__year__gte=1980,
  677
+                                    birthday__year__lte=1989).exists():
  678
+                          yield ('80s', _('in the eighties'))
  679
+                      if qs.filter(birthday__year__gte=1990,
  680
+                                    birthday__year__lte=1999).exists():
  681
+                          yield ('90s', _('in the nineties'))
  682
+
  683
+    * a tuple, where the first element is a field name and the second
  684
+      element is a class inheriting from
  685
+      :mod:`django.contrib.admin.FieldListFilter`, for example::
  686
+
  687
+          from django.contrib.admin import BooleanFieldListFilter
  688
+
  689
+          class PersonAdmin(ModelAdmin):
  690
+              list_filter = (
  691
+                  ('is_staff', BooleanFieldListFilter),
  692
+              )
  693
+
  694
+      .. note::
  695
+
  696
+          The ``FieldListFilter`` API is currently considered internal
  697
+          and prone to refactoring.
698 698
 
699 699
 .. attribute:: ModelAdmin.list_max_show_all
700 700
 
@@ -1076,11 +1076,11 @@ templates used by the :class:`ModelAdmin` views:
1076 1076
     However, the ``self.my_view`` function registered above suffers from two
1077 1077
     problems:
1078 1078
 
1079  
-      * It will *not* perform any permission checks, so it will be accessible
1080  
-        to the general public.
1081  
-      * It will *not* provide any header details to prevent caching. This means
1082  
-        if the page retrieves data from the database, and caching middleware is
1083  
-        active, the page could show outdated information.
  1079
+    * It will *not* perform any permission checks, so it will be accessible
  1080
+      to the general public.
  1081
+    * It will *not* provide any header details to prevent caching. This means
  1082
+      if the page retrieves data from the database, and caching middleware is
  1083
+      active, the page could show outdated information.
1084 1084
 
1085 1085
     Since this is usually not what you want, Django provides a convenience
1086 1086
     wrapper to check permissions and mark the view as non-cacheable. This
@@ -1356,8 +1356,8 @@ information.
1356 1356
 
1357 1357
     Django provides two subclasses of ``InlineModelAdmin`` and they are:
1358 1358
 
1359  
-        * :class:`~django.contrib.admin.TabularInline`
1360  
-        * :class:`~django.contrib.admin.StackedInline`
  1359
+    * :class:`~django.contrib.admin.TabularInline`
  1360
+    * :class:`~django.contrib.admin.StackedInline`
1361 1361
 
1362 1362
     The difference between these two is merely the template used to render
1363 1363
     them.
@@ -1735,11 +1735,11 @@ Templates which may be overridden per app or model
1735 1735
 Not every template in ``contrib/admin/templates/admin`` may be overridden per
1736 1736
 app or per model. The following can:
1737 1737
 
1738  
-    * ``app_index.html``
1739  
-    * ``change_form.html``
1740  
-    * ``change_list.html``
1741  
-    * ``delete_confirmation.html``
1742  
-    * ``object_history.html``
  1738
+* ``app_index.html``
  1739
+* ``change_form.html``
  1740
+* ``change_list.html``
  1741
+* ``delete_confirmation.html``
  1742
+* ``object_history.html``
1743 1743
 
1744 1744
 For those templates that cannot be overridden in this way, you may still
1745 1745
 override them for your entire project. Just place the new version in your
@@ -1920,28 +1920,28 @@ accessible using Django's :ref:`URL reversing system <naming-url-patterns>`.
1920 1920
 
1921 1921
 The :class:`AdminSite` provides the following named URL patterns:
1922 1922
 
1923  
-    ======================  ========================  =============
1924  
-    Page                    URL name                  Parameters
1925  
-    ======================  ========================  =============
1926  
-    Index                   ``index``
1927  
-    Logout                  ``logout``
1928  
-    Password change         ``password_change``
1929  
-    Password change done    ``password_change_done``
1930  
-    i18n javascript         ``jsi18n``
1931  
-    Application index page  ``app_list``              ``app_label``
1932  
-    ======================  ========================  =============
  1923
+======================  ========================  =============
  1924
+Page                    URL name                  Parameters
  1925
+======================  ========================  =============
  1926
+Index                   ``index``
  1927
+Logout                  ``logout``
  1928
+Password change         ``password_change``
  1929
+Password change done    ``password_change_done``
  1930
+i18n javascript         ``jsi18n``
  1931
+Application index page  ``app_list``              ``app_label``
  1932
+======================  ========================  =============
1933 1933
 
1934 1934
 Each :class:`ModelAdmin` instance provides an additional set of named URLs:
1935 1935
 
1936  
-    ======================  ===============================================   =============
1937  
-    Page                    URL name                                          Parameters
1938  
-    ======================  ===============================================   =============
1939  
-    Changelist              ``{{ app_label }}_{{ model_name }}_changelist``
1940  
-    Add                     ``{{ app_label }}_{{ model_name }}_add``
1941  
-    History                 ``{{ app_label }}_{{ model_name }}_history``      ``object_id``
1942  
-    Delete                  ``{{ app_label }}_{{ model_name }}_delete``       ``object_id``
1943  
-    Change                  ``{{ app_label }}_{{ model_name }}_change``       ``object_id``
1944  
-    ======================  ===============================================   =============
  1936
+======================  ===============================================   =============
  1937
+Page                    URL name                                          Parameters
  1938
+======================  ===============================================   =============
  1939
+Changelist              ``{{ app_label }}_{{ model_name }}_changelist``
  1940
+Add                     ``{{ app_label }}_{{ model_name }}_add``
  1941
+History                 ``{{ app_label }}_{{ model_name }}_history``      ``object_id``
  1942
+Delete                  ``{{ app_label }}_{{ model_name }}_delete``       ``object_id``
  1943
+Change                  ``{{ app_label }}_{{ model_name }}_change``       ``object_id``
  1944
+======================  ===============================================   =============
1945 1945
 
1946 1946
 These named URLs are registered with the application namespace ``admin``, and
1947 1947
 with an instance namespace corresponding to the name of the Site instance.
18  docs/ref/contrib/comments/example.txt
@@ -125,12 +125,12 @@ moderate comments"``) can approve and delete comments. This can also be
125 125
 done through the ``admin`` as you'll see later. You might also want to
126 126
 customize the following templates:
127 127
 
128  
-  * ``flag.html``
129  
-  * ``flagged.html``
130  
-  * ``approve.html``
131  
-  * ``approved.html``
132  
-  * ``delete.html``
133  
-  * ``deleted.html``
  128
+* ``flag.html``
  129
+* ``flagged.html``
  130
+* ``approve.html``
  131
+* ``approved.html``
  132
+* ``delete.html``
  133
+* ``deleted.html``
134 134
 
135 135
 found under the directory structure we saw for ``form.html``.
136 136
 
@@ -185,9 +185,9 @@ in-built with :doc:`generic comment moderation
185 185
 </ref/contrib/comments/moderation>`. The comment moderation has the following
186 186
 features (all of which or only certain can be enabled):
187 187
 
188  
-  * Enable comments for a particular model instance.
189  
-  * Close comments after a particular (user-defined) number of days.
190  
-  * Email new comments to the site-staff.
  188
+* Enable comments for a particular model instance.
  189
+* Close comments after a particular (user-defined) number of days.
  190
+* Email new comments to the site-staff.
191 191
 
192 192
 To enable comment moderation, we subclass the :class:`CommentModerator` and
193 193
 register it with the moderation features we want. Let us suppose we want to
100  docs/ref/contrib/localflavor.txt
@@ -36,49 +36,49 @@ Supported countries
36 36
 
37 37
 Countries currently supported by :mod:`~django.contrib.localflavor` are:
38 38
 
39  
-    * Argentina_
40  
-    * Australia_
41  
-    * Austria_
42  
-    * Belgium_
43  
-    * Brazil_
44  
-    * Canada_
45  
-    * Chile_
46  
-    * China_
47  
-    * Colombia_
48  
-    * Croatia_
49  
-    * Czech_
50  
-    * Ecuador_
51  
-    * Finland_
52  
-    * France_
53  
-    * Germany_
54  
-    * Iceland_
55  
-    * India_
56  
-    * Indonesia_
57  
-    * Ireland_
58  
-    * Israel_
59  
-    * Italy_
60  
-    * Japan_
61  
-    * Kuwait_
62  
-    * Macedonia_
63  
-    * Mexico_
64  
-    * `The Netherlands`_
65  
-    * Norway_
66  
-    * Peru_
67  
-    * Poland_
68  
-    * Portugal_
69  
-    * Paraguay_
70  
-    * Romania_
71  
-    * Russia_
72  
-    * Slovakia_
73  
-    * Slovenia_
74  
-    * `South Africa`_
75  
-    * Spain_
76  
-    * Sweden_
77  
-    * Switzerland_
78  
-    * Turkey_
79  
-    * `United Kingdom`_
80  
-    * `United States of America`_
81  
-    * Uruguay_
  39
+* Argentina_
  40
+* Australia_
  41
+* Austria_
  42
+* Belgium_
  43
+* Brazil_
  44
+* Canada_
  45
+* Chile_
  46
+* China_
  47
+* Colombia_
  48
+* Croatia_
  49
+* Czech_
  50
+* Ecuador_
  51
+* Finland_
  52
+* France_
  53
+* Germany_
  54
+* Iceland_
  55
+* India_
  56
+* Indonesia_
  57
+* Ireland_
  58
+* Israel_
  59
+* Italy_
  60
+* Japan_
  61
+* Kuwait_
  62
+* Macedonia_
  63
+* Mexico_
  64
+* `The Netherlands`_
  65
+* Norway_
  66
+* Peru_
  67
+* Poland_
  68
+* Portugal_
  69
+* Paraguay_
  70
+* Romania_
  71
+* Russia_
  72
+* Slovakia_
  73
+* Slovenia_
  74
+* `South Africa`_
  75
+* Spain_
  76
+* Sweden_
  77
+* Switzerland_
  78
+* Turkey_
  79
+* `United Kingdom`_
  80
+* `United States of America`_
  81
+* Uruguay_
82 82
 
83 83
 The ``django.contrib.localflavor`` package also includes a ``generic`` subpackage,
84 84
 containing useful code that is not specific to one particular country or culture.
@@ -1286,13 +1286,13 @@ United States of America (``us``)
1286 1286
     A form field that validates input as a U.S. Social Security Number (SSN).
1287 1287
     A valid SSN must obey the following rules:
1288 1288
 
1289  
-        * Format of XXX-XX-XXXX
1290  
-        * No group of digits consisting entirely of zeroes
1291  
-        * Leading group of digits cannot be 666
1292  
-        * Number not in promotional block 987-65-4320 through 987-65-4329
1293  
-        * Number not one known to be invalid due to widespread promotional
1294  
-          use or distribution (e.g., the Woolworth's number or the 1962
1295  
-          promotional number)
  1289
+    * Format of XXX-XX-XXXX
  1290
+    * No group of digits consisting entirely of zeroes
  1291
+    * Leading group of digits cannot be 666
  1292
+    * Number not in promotional block 987-65-4320 through 987-65-4329
  1293
+    * Number not one known to be invalid due to widespread promotional
  1294
+      use or distribution (e.g., the Woolworth's number or the 1962
  1295
+      promotional number)
1296 1296
 
1297 1297
 .. class:: us.forms.USStateField
1298 1298
 
390  docs/ref/models/querysets.txt
@@ -24,57 +24,57 @@ actually occurs until you do something to evaluate the queryset.
24 24
 
25 25
 You can evaluate a ``QuerySet`` in the following ways:
26 26
 
27  
-    * **Iteration.** A ``QuerySet`` is iterable, and it executes its database
28  
-      query the first time you iterate over it. For example, this will print
29  
-      the headline of all entries in the database::
  27
+* **Iteration.** A ``QuerySet`` is iterable, and it executes its database
  28
+  query the first time you iterate over it. For example, this will print
  29
+  the headline of all entries in the database::
30 30
 
31  
-          for e in Entry.objects.all():
32  
-              print e.headline
  31
+      for e in Entry.objects.all():
  32
+          print e.headline
33 33
 
34  
-    * **Slicing.** As explained in :ref:`limiting-querysets`, a ``QuerySet`` can
35  
-      be sliced, using Python's array-slicing syntax. Usually slicing a
36  
-      ``QuerySet`` returns another (unevaluated) ``QuerySet``, but Django will
37  
-      execute the database query if you use the "step" parameter of slice
38  
-      syntax.
  34
+* **Slicing.** As explained in :ref:`limiting-querysets`, a ``QuerySet`` can
  35
+  be sliced, using Python's array-slicing syntax. Usually slicing a
  36
+  ``QuerySet`` returns another (unevaluated) ``QuerySet``, but Django will
  37
+  execute the database query if you use the "step" parameter of slice
  38
+  syntax.
39 39
 
40  
-    * **Pickling/Caching.** See the following section for details of what
41  
-      is involved when `pickling QuerySets`_. The important thing for the
42  
-      purposes of this section is that the results are read from the database.
  40
+* **Pickling/Caching.** See the following section for details of what
  41
+  is involved when `pickling QuerySets`_. The important thing for the
  42
+  purposes of this section is that the results are read from the database.
43 43
 
44  
-    * **repr().** A ``QuerySet`` is evaluated when you call ``repr()`` on it.
45  
-      This is for convenience in the Python interactive interpreter, so you can
46  
-      immediately see your results when using the API interactively.
  44
+* **repr().** A ``QuerySet`` is evaluated when you call ``repr()`` on it.
  45
+  This is for convenience in the Python interactive interpreter, so you can
  46
+  immediately see your results when using the API interactively.
47 47
 
48  
-    * **len().** A ``QuerySet`` is evaluated when you call ``len()`` on it.
49  
-      This, as you might expect, returns the length of the result list.
  48
+* **len().** A ``QuerySet`` is evaluated when you call ``len()`` on it.
  49
+  This, as you might expect, returns the length of the result list.
50 50
 
51  
-      Note: *Don't* use ``len()`` on ``QuerySet``\s if all you want to do is
52  
-      determine the number of records in the set. It's much more efficient to
53  
-      handle a count at the database level, using SQL's ``SELECT COUNT(*)``,
54  
-      and Django provides a ``count()`` method for precisely this reason. See
55  
-      ``count()`` below.
  51
+  Note: *Don't* use ``len()`` on ``QuerySet``\s if all you want to do is
  52
+  determine the number of records in the set. It's much more efficient to
  53
+  handle a count at the database level, using SQL's ``SELECT COUNT(*)``,
  54
+  and Django provides a ``count()`` method for precisely this reason. See
  55
+  ``count()`` below.
56 56
 
57  
-    * **list().** Force evaluation of a ``QuerySet`` by calling ``list()`` on
58  
-      it. For example::
  57
+* **list().** Force evaluation of a ``QuerySet`` by calling ``list()`` on
  58
+  it. For example::
59 59
 
60  
-          entry_list = list(Entry.objects.all())
  60
+      entry_list = list(Entry.objects.all())
61 61
 
62  
-      Be warned, though, that this could have a large memory overhead, because
63  
-      Django will load each element of the list into memory. In contrast,
64  
-      iterating over a ``QuerySet`` will take advantage of your database to
65  
-      load data and instantiate objects only as you need them.
  62
+  Be warned, though, that this could have a large memory overhead, because
  63
+  Django will load each element of the list into memory. In contrast,
  64
+  iterating over a ``QuerySet`` will take advantage of your database to
  65
+  load data and instantiate objects only as you need them.
66 66
 
67  
-    * **bool().** Testing a ``QuerySet`` in a boolean context, such as using
68  
-      ``bool()``, ``or``, ``and`` or an ``if`` statement, will cause the query
69  
-      to be executed. If there is at least one result, the ``QuerySet`` is
70  
-      ``True``, otherwise ``False``. For example::
  67
+* **bool().** Testing a ``QuerySet`` in a boolean context, such as using
  68
+  ``bool()``, ``or``, ``and`` or an ``if`` statement, will cause the query
  69
+  to be executed. If there is at least one result, the ``QuerySet`` is
  70
+  ``True``, otherwise ``False``. For example::
71 71
 
72  
-          if Entry.objects.filter(headline="Test"):
73  
-             print "There is at least one Entry with the headline Test"
  72
+      if Entry.objects.filter(headline="Test"):
  73
+         print "There is at least one Entry with the headline Test"
74 74
 
75  
-      Note: *Don't* use this if all you want to do is determine if at least one
76  
-      result exists, and don't need the actual objects. It's more efficient to
77  
-      use :meth:`exists() <QuerySet.exists>` (see below).
  75
+  Note: *Don't* use this if all you want to do is determine if at least one
  76
+  result exists, and don't need the actual objects. It's more efficient to
  77
+  use :meth:`exists() <QuerySet.exists>` (see below).
78 78
 
79 79
 .. _pickling QuerySets:
80 80
 
@@ -411,35 +411,35 @@ Example::
411 411
 
412 412
 A few subtleties that are worth mentioning:
413 413
 
414  
-    * If you have a field called ``foo`` that is a
415  
-      :class:`~django.db.models.ForeignKey`, the default ``values()`` call
416  
-      will return a dictionary key called ``foo_id``, since this is the name
417  
-      of the hidden model attribute that stores the actual value (the ``foo``
418  
-      attribute refers to the related model). When you are calling
419  
-      ``values()`` and passing in field names, you can pass in either ``foo``
420  
-      or ``foo_id`` and you will get back the same thing (the dictionary key
421  
-      will match the field name you passed in).
  414
+* If you have a field called ``foo`` that is a
  415
+  :class:`~django.db.models.ForeignKey`, the default ``values()`` call
  416
+  will return a dictionary key called ``foo_id``, since this is the name
  417
+  of the hidden model attribute that stores the actual value (the ``foo``
  418
+  attribute refers to the related model). When you are calling
  419
+  ``values()`` and passing in field names, you can pass in either ``foo``
  420
+  or ``foo_id`` and you will get back the same thing (the dictionary key
  421
+  will match the field name you passed in).
422 422
 
423  
-      For example::
  423
+  For example::
424 424
 
425  
-        >>> Entry.objects.values()
426  
-        [{'blog_id': 1, 'headline': u'First Entry', ...}, ...]
  425
+    >>> Entry.objects.values()
  426
+    [{'blog_id': 1, 'headline': u'First Entry', ...}, ...]
427 427
 
428  
-        >>> Entry.objects.values('blog')
429  
-        [{'blog': 1}, ...]
  428
+    >>> Entry.objects.values('blog')
  429
+    [{'blog': 1}, ...]
430 430
 
431  
-        >>> Entry.objects.values('blog_id')
432  
-        [{'blog_id': 1}, ...]
  431
+    >>> Entry.objects.values('blog_id')
  432
+    [{'blog_id': 1}, ...]
433 433
 
434  
-    * When using ``values()`` together with :meth:`distinct()`, be aware that
435  
-      ordering can affect the results. See the note in :meth:`distinct` for
436  
-      details.
  434
+* When using ``values()`` together with :meth:`distinct()`, be aware that
  435
+  ordering can affect the results. See the note in :meth:`distinct` for
  436
+  details.
437 437
 
438  
-    * If you use a ``values()`` clause after an :meth:`extra()` call,
439  
-      any fields defined by a ``select`` argument in the :meth:`extra()` must
440  
-      be explicitly included in the ``values()`` call. Any :meth:`extra()` call
441  
-      made after a ``values()`` call will have its extra selected fields
442  
-      ignored.
  438
+* If you use a ``values()`` clause after an :meth:`extra()` call,
  439
+  any fields defined by a ``select`` argument in the :meth:`extra()` must
  440
+  be explicitly included in the ``values()`` call. Any :meth:`extra()` call
  441
+  made after a ``values()`` call will have its extra selected fields
  442
+  ignored.
443 443
 
444 444
 A ``ValuesQuerySet`` is useful when you know you're only going to need values
445 445
 from a small number of the available fields and you won't need the
@@ -524,11 +524,11 @@ model.
524 524
 ``datetime.datetime`` object in the result list is "truncated" to the given
525 525
 ``type``.
526 526
 
527  
-    * ``"year"`` returns a list of all distinct year values for the field.
528  
-    * ``"month"`` returns a list of all distinct year/month values for the
529  
-      field.
530  
-    * ``"day"`` returns a list of all distinct year/month/day values for the
531  
-      field.
  527
+* ``"year"`` returns a list of all distinct year values for the field.
  528
+* ``"month"`` returns a list of all distinct year/month values for the
  529
+  field.
  530
+* ``"day"`` returns a list of all distinct year/month/day values for the
  531
+  field.
532 532
 
533 533
 ``order``, which defaults to ``'ASC'``, should be either ``'ASC'`` or
534 534
 ``'DESC'``. This specifies how to order the results.
@@ -832,153 +832,155 @@ principle, so you should avoid them if possible.
832 832
 Specify one or more of ``params``, ``select``, ``where`` or ``tables``. None
833 833
 of the arguments is required, but you should use at least one of them.
834 834
 
835  
-    * ``select``
836  
-        The ``select`` argument lets you put extra fields in the ``SELECT``
837  
-        clause.  It should be a dictionary mapping attribute names to SQL
838  
-        clauses to use to calculate that attribute.
  835
+* ``select``
839 836
 
840  
-        Example::
  837
+  The ``select`` argument lets you put extra fields in the ``SELECT``
  838
+  clause.  It should be a dictionary mapping attribute names to SQL
  839
+  clauses to use to calculate that attribute.
841 840
 
842  
-            Entry.objects.extra(select={'is_recent': "pub_date > '2006-01-01'"})
  841
+  Example::
843 842
 
844  
-        As a result, each ``Entry`` object will have an extra attribute,
845  
-        ``is_recent``, a boolean representing whether the entry's ``pub_date``
846  
-        is greater than Jan. 1, 2006.
  843
+      Entry.objects.extra(select={'is_recent': "pub_date > '2006-01-01'"})
847 844
 
848  
-        Django inserts the given SQL snippet directly into the ``SELECT``
849  
-        statement, so the resulting SQL of the above example would be something
850  
-        like::
  845
+  As a result, each ``Entry`` object will have an extra attribute,
  846
+  ``is_recent``, a boolean representing whether the entry's ``pub_date``
  847
+  is greater than Jan. 1, 2006.
851 848
 
852  
-            SELECT blog_entry.*, (pub_date > '2006-01-01') AS is_recent
853  
-            FROM blog_entry;
  849
+  Django inserts the given SQL snippet directly into the ``SELECT``
  850
+  statement, so the resulting SQL of the above example would be something
  851
+  like::
854 852
 
  853
+      SELECT blog_entry.*, (pub_date > '2006-01-01') AS is_recent
  854
+      FROM blog_entry;
855 855
 
856  
-        The next example is more advanced; it does a subquery to give each
857  
-        resulting ``Blog`` object an ``entry_count`` attribute, an integer count
858  
-        of associated ``Entry`` objects::
859 856
 
860  
-            Blog.objects.extra(
861  
-                select={
862  
-                    'entry_count': 'SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id'
863  
-                },
864  
-            )
  857
+  The next example is more advanced; it does a subquery to give each
  858
+  resulting ``Blog`` object an ``entry_count`` attribute, an integer count
  859
+  of associated ``Entry`` objects::
865 860
 
866  
-        In this particular case, we're exploiting the fact that the query will
867  
-        already contain the ``blog_blog`` table in its ``FROM`` clause.
  861
+      Blog.objects.extra(
  862
+          select={
  863
+              'entry_count': 'SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id'
  864
+          },
  865
+      )
868 866
 
869  
-        The resulting SQL of the above example would be::
  867
+  In this particular case, we're exploiting the fact that the query will
  868
+  already contain the ``blog_blog`` table in its ``FROM`` clause.