From e249b0ec4d8bb3880883927a1c732d882bcdfa48 Mon Sep 17 00:00:00 2001
From: Russell Keith-Magee <russell@keith-magee.com>
Date: Thu, 16 Apr 2009 13:28:58 +0000
Subject: [PATCH] [1.0.X] Fixed #10776 -- Added metadata targets for the
 contrib.admin docs, and used one of those targets to clarify the SlugField
 docs. Thanks to ernop for the suggestion, and timo for the patch.

Merge of r10564 from trunk.

git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.0.X@10570 bcc190cf-cafb-0310-a4f2-bffc1f526a37
---
 docs/ref/contrib/admin.txt | 74 +++++++++++++++-----------------------
 docs/ref/models/fields.txt |  4 +++
 2 files changed, 32 insertions(+), 46 deletions(-)

diff --git a/docs/ref/contrib/admin.txt b/docs/ref/contrib/admin.txt
index 7444937a68..9ac339e99b 100644
--- a/docs/ref/contrib/admin.txt
+++ b/docs/ref/contrib/admin.txt
@@ -7,6 +7,8 @@ The Django admin site
 .. module:: django.contrib.admin
    :synopsis: Django's admin site.
 
+.. currentmodule:: django.contrib.admin
+
 One of the most powerful parts of Django is the automatic admin interface. It
 reads metadata in your model to provide a powerful and production-ready
 interface that content producers can immediately use to start adding content to
@@ -38,7 +40,7 @@ There are five steps in activating the Django admin site:
        ``ModelAdmin`` classes.
 
     5. Hook the ``AdminSite`` instance into your URLconf.
-   
+
 .. seealso::
 
     For information about serving the media files (images, JavaScript, and CSS)
@@ -47,6 +49,8 @@ There are five steps in activating the Django admin site:
 ``ModelAdmin`` objects
 ======================
 
+.. class:: ModelAdmin
+
 The ``ModelAdmin`` class is the representation of a model in the admin
 interface. These are stored in a file named ``admin.py`` in your application.
 Let's take a look at a very simple example of the ``ModelAdmin``::
@@ -82,8 +86,7 @@ subclass::
     class AuthorAdmin(admin.ModelAdmin):
         date_hierarchy = 'pub_date'
 
-``date_hierarchy``
-~~~~~~~~~~~~~~~~~~
+.. attribute:: ModelAdmin.date_hierarchy
 
 Set ``date_hierarchy`` to the name of a ``DateField`` or ``DateTimeField`` in
 your model, and the change list page will include a date-based drilldown
@@ -93,8 +96,7 @@ Example::
 
     date_hierarchy = 'pub_date'
 
-``form``
-~~~~~~~~
+.. attribute:: ModelAdmin.form
 
 By default a ``ModelForm`` is dynamically created for your model. It is used
 to create the form presented on both the add/change pages. You can easily
@@ -103,8 +105,7 @@ add/change pages.
 
 For an example see the section `Adding custom validation to the admin`_.
 
-``fieldsets``
-~~~~~~~~~~~~~
+.. attribute:: ModelAdmin.fieldsets
 
 Set ``fieldsets`` to control the layout of admin "add" and "change" pages.
 
@@ -183,8 +184,7 @@ The ``field_options`` dictionary can have the following keys:
         ``django.utils.html.escape()`` to escape any HTML special
         characters.
 
-``fields``
-~~~~~~~~~~
+.. attribute:: ModelAdmin.fields
 
 Use this option as an alternative to ``fieldsets`` if the layout does not
 matter and if you want to only show a subset of the available fields in the
@@ -203,8 +203,7 @@ displayed, sequentially, in the form.
     dictionary key that is within the ``fieldsets`` option, as described in
     the previous section.
 
-``exclude``
-~~~~~~~~~~~
+.. attribute:: ModelAdmin.exclude
 
 This attribute, if given, should be a list of field names to exclude from the
 form.
@@ -229,22 +228,19 @@ Since the Author model only has three fields, ``name``, ``title``, and
 ``birth_date``, the forms resulting from the above declarations will contain
 exactly the same fields.
 
-``filter_horizontal``
-~~~~~~~~~~~~~~~~~~~~~
+.. attribute:: ModelAdmin.filter_horizontal
 
 Use a nifty unobtrusive JavaScript "filter" interface instead of the
 usability-challenged ``<select multiple>`` in the admin form. The value is a
 list of fields that should be displayed as a horizontal filter interface. See
 ``filter_vertical`` to use a vertical interface.
 
-``filter_vertical``
-~~~~~~~~~~~~~~~~~~~
+.. attribute:: ModelAdmin.filter_vertical
 
 Same as ``filter_horizontal``, but is a vertical display of the filter
 interface.
 
-``list_display``
-~~~~~~~~~~~~~~~~
+.. attribute:: ModelAdmin.list_display
 
 Set ``list_display`` to control which fields are displayed on the change list
 page of the admin.
@@ -381,8 +377,7 @@ A few special cases to note about ``list_display``:
       The above will tell Django to order by the ``first_name`` field when
       trying to sort by ``colored_first_name`` in the admin.
 
-``list_display_links``
-~~~~~~~~~~~~~~~~~~~~~~
+.. attribute:: ModelAdmin.list_display_links
 
 Set ``list_display_links`` to control which fields in ``list_display`` should
 be linked to the "change" page for an object.
@@ -405,8 +400,7 @@ the change list page::
         list_display = ('first_name', 'last_name', 'birthday')
         list_display_links = ('first_name', 'last_name')
 
-``list_filter``
-~~~~~~~~~~~~~~~
+.. attribute:: ModelAdmin.list_filter
 
 Set ``list_filter`` to activate filters in the right sidebar of the change list
 page of the admin. This should be a list of field names, and each specified
@@ -426,14 +420,12 @@ The above code results in an admin change list page that looks like this:
 
 (This example also has ``search_fields`` defined. See below.)
 
-``list_per_page``
-~~~~~~~~~~~~~~~~~
+.. attribute:: ModelAdmin.list_per_page
 
 Set ``list_per_page`` to control how many items appear on each paginated admin
 change list page. By default, this is set to ``100``.
 
-``list_select_related``
-~~~~~~~~~~~~~~~~~~~~~~~
+.. attribute:: ModelAdmin.list_select_related
 
 Set ``list_select_related`` to tell Django to use ``select_related()`` in
 retrieving the list of objects on the admin change list page. This can save you
@@ -447,13 +439,11 @@ if one of the ``list_display`` fields is a ``ForeignKey``.
 For more on ``select_related()``, see
 :ref:`the select_related() docs <select-related>`.
 
-``inlines``
-~~~~~~~~~~~
+.. attribute:: ModelAdmin.inlines
 
 See ``InlineModelAdmin`` objects below.
 
-``ordering``
-~~~~~~~~~~~~
+.. attribute:: ModelAdmin.ordering
 
 Set ``ordering`` to specify how objects on the admin change list page should be
 ordered. This should be a list or tuple in the same format as a model's
@@ -466,8 +456,7 @@ If this isn't provided, the Django admin will use the model's default ordering.
     Django will only honor the first element in the list/tuple; any others
     will be ignored.
 
-``prepopulated_fields``
-~~~~~~~~~~~~~~~~~~~~~~~
+.. attribute:: ModelAdmin.prepopulated_fields
 
 Set ``prepopulated_fields`` to a dictionary mapping field names to the fields
 it should prepopulate from::
@@ -485,8 +474,7 @@ dashes for spaces).
 ``prepopulated_fields`` doesn't accept ``DateTimeField``, ``ForeignKey``, nor
 ``ManyToManyField`` fields.
 
-``radio_fields``
-~~~~~~~~~~~~~~~~
+.. attribute:: ModelAdmin.radio_fields
 
 By default, Django's admin uses a select-box interface (<select>) for
 fields that are ``ForeignKey`` or have ``choices`` set. If a field is present
@@ -502,8 +490,7 @@ You have the choice of using ``HORIZONTAL`` or ``VERTICAL`` from the
 Don't include a field in ``radio_fields`` unless it's a ``ForeignKey`` or has
 ``choices`` set.
 
-``raw_id_fields``
-~~~~~~~~~~~~~~~~~
+.. attribute:: ModelAdmin.raw_id_fields
 
 By default, Django's admin uses a select-box interface (<select>) for
 fields that are ``ForeignKey``. Sometimes you don't want to incur the
@@ -516,8 +503,7 @@ into a ``Input`` widget for either a ``ForeignKey`` or ``ManyToManyField``::
     class ArticleAdmin(admin.ModelAdmin):
         raw_id_fields = ("newspaper",)
 
-``save_as``
-~~~~~~~~~~~
+.. attribute:: ModelAdmin.save_as
 
 Set ``save_as`` to enable a "save as" feature on admin change forms.
 
@@ -530,8 +516,7 @@ rather than the old object.
 
 By default, ``save_as`` is set to ``False``.
 
-``save_on_top``
-~~~~~~~~~~~~~~~
+.. attribute:: ModelAdmin.save_on_top
 
 Set ``save_on_top`` to add save buttons across the top of your admin change
 forms.
@@ -541,8 +526,7 @@ Normally, the save buttons appear only at the bottom of the forms. If you set
 
 By default, ``save_on_top`` is set to ``False``.
 
-``search_fields``
-~~~~~~~~~~~~~~~~~
+.. attribute:: ModelAdmin.search_fields
 
 Set ``search_fields`` to enable a search box on the admin change list page.
 This should be set to a list of field names that will be searched whenever
@@ -602,8 +586,7 @@ with an operator:
 ``ModelAdmin`` methods
 ----------------------
 
-``save_model(self, request, obj, form, change)``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. method:: ModelAdmin.save_model(self, request, obj, form, change)
 
 The ``save_model`` method is given the ``HttpRequest``, a model instance,
 a ``ModelForm`` instance and a boolean value based on whether it is adding or
@@ -616,8 +599,7 @@ For example to attach ``request.user`` to the object prior to saving::
             obj.user = request.user
             obj.save()
 
-``save_formset(self, request, form, formset, change)``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. method:: ModelAdmin.save_formset(self, request, form, formset, change)
 
 The ``save_formset`` method is given the ``HttpRequest``, the parent
 ``ModelForm`` instance and a boolean value based on whether it is adding or
@@ -692,7 +674,7 @@ parent model. These are called inlines. Suppose you have these two models::
         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 
+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):
diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt
index 6630b7bc26..2ec74e4306 100644
--- a/docs/ref/models/fields.txt
+++ b/docs/ref/models/fields.txt
@@ -689,6 +689,10 @@ default length of 50.
 
 Implies setting :attr:`Field.db_index` to ``True``.
 
+It is often useful to automatically prepopulate a SlugField based on the value
+of some other value.  You can do this automatically in the admin using
+:attr:`~django.contrib.admin.ModelAdmin.prepopulated_fields`.
+
 ``SmallIntegerField``
 ---------------------