[soc2009/model-validation] Merged to trunk at r11791

git-svn-id: http://code.djangoproject.com/svn/django/branches/soc2009/model-validation@11798 bcc190cf-cafb-0310-a4f2-bffc1f526a37

4 files changed, 119 insertions, 86 deletions

diff --git a/docs/ref/contrib/csrf.txt b/docs/ref/contrib/csrf.txt
index c1bdb59cd1..ea76fc3739 100644
--- a/docs/ref/contrib/csrf.txt
+++ b/docs/ref/contrib/csrf.txt
@@ -46,7 +46,7 @@ To enable CSRF protection for your views, follow these steps:
        ``django.views.decorators.csrf.csrf_protect`` on particular views you
        want to protect (see below).
 
-    2. In any template that uses a POST form, use the ``csrf_token`` tag inside
+    2. In any template that uses a POST form, use the :ttag:`csrf_token` tag inside
        the ``<form>`` element if the form is for an internal URL, e.g.::
 
            <form action="" method="POST">{% csrf_token %}
@@ -123,14 +123,14 @@ as ``CsrfResponseMiddleware``, and it can be used by following these steps:
 
        ``CsrfResponseMiddleware`` needs to process the response before things
        like compression or setting ofETags happen to the response, so it must
-       come after ``GZipMiddleware``, ``CommonMiddleware`` and 
+       come after ``GZipMiddleware``, ``CommonMiddleware`` and
        ``ConditionalGetMiddleware`` in the list. It also must come after
        ``CsrfViewMiddleware``.
 
 Use of the ``CsrfResponseMiddleware`` is not recommended because of the
 performance hit it imposes, and because of a potential security problem (see
 below).  It can be used as an interim measure until applications have been
-updated to use the ``{% csrf_token %}`` tag.  It is deprecated and will be
+updated to use the :ttag:`csrf_token` tag.  It is deprecated and will be
 removed in Django 1.4.
 
 Django 1.1 and earlier provided a single ``CsrfMiddleware`` class.  This is also
@@ -153,6 +153,8 @@ launch a CSRF attack on your site against that user.  The
 ``@csrf_response_exempt`` decorator can be used to fix this, but only if the
 page doesn't also contain internal forms that require the token.
 
+.. _ref-csrf-upgrading-notes:
+
 Upgrading notes
 ---------------
 
@@ -199,7 +201,7 @@ Note that contrib apps, such as the admin, have been updated to use the
 ``CsrfViewMiddleware`` to your settings.  However, if you have supplied
 customised templates to any of the view functions of contrib apps (whether
 explicitly via a keyword argument, or by overriding built-in templates), **you
-MUST update them** to include the ``csrf_token`` template tag as described
+MUST update them** to include the :ttag:`csrf_token` template tag as described
 above, or they will stop working.  (If you cannot update these templates for
 some reason, you will be forced to use ``CsrfResponseMiddleware`` for these
 views to continue working).
@@ -364,7 +366,7 @@ exactly that.
 Caching
 =======
 
-If the ``csrf_token`` template tag is used by a template (or the ``get_token``
+If the :ttag:`csrf_token` template tag is used by a template (or the ``get_token``
 function is called some other way), ``CsrfViewMiddleware`` will add a cookie and
 a ``Vary: Cookie`` header to the response.  Similarly,
 ``CsrfResponseMiddleware`` will send the ``Vary: Cookie`` header if it inserted
diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt
index f657db20f4..80e368286e 100644
--- a/docs/ref/django-admin.txt
+++ b/docs/ref/django-admin.txt
@@ -78,11 +78,9 @@ Examples of output::
 Displaying debug output
 -----------------------
 
-.. django-admin-option:: --verbosity <amount>
-
-Use ``--verbosity`` to specify the amount of notification and debug information
+Use :djadminopt:`--verbosity` to specify the amount of notification and debug information
 that ``django-admin.py`` should print to the console. For more details, see the
-documentation for the :ref:`default options for django-admin.py <django-admin-verbosity>`.
+documentation for the :djadminopt:`--verbosity` option.
 
 Available subcommands
 =====================
@@ -90,6 +88,8 @@ Available subcommands
 cleanup
 -------
 
+.. django-admin:: cleanup
+
 .. versionadded:: 1.0
 
 Can be run as a cronjob or directly to clean out old data from the database
@@ -98,17 +98,16 @@ Can be run as a cronjob or directly to clean out old data from the database
 compilemessages
 ---------------
 
+.. django-admin:: compilemessages
+
 .. versionchanged:: 1.0
    Before 1.0 this was the "bin/compile-messages.py" command.
 
 Compiles .po files created with ``makemessages`` to .mo files for use with
 the builtin gettext support. See :ref:`topics-i18n`.
 
---locale
-~~~~~~~~
-
-Use the ``--locale`` or ``-l`` option to specify the locale to process.
-If not provided all locales are processed.
+Use the :djadminopt:`--locale`` option to specify the locale to process.
+If not provided, all locales are processed.
 
 Example usage::
 
@@ -117,7 +116,7 @@ Example usage::
 createcachetable
 ----------------
 
-.. django-admin:: createcachetable <tablename>
+.. django-admin:: createcachetable
 
 Creates a cache table named ``tablename`` for use with the database cache
 backend. See :ref:`topics-cache` for more information.
@@ -183,10 +182,10 @@ example, the default settings don't define ``ROOT_URLCONF``, so
 Note that Django's default settings live in ``django/conf/global_settings.py``,
 if you're ever curious to see the full list of defaults.
 
-dumpdata
---------
+dumpdata <appname appname appname.Model ...>
+--------------------------------------------
 
-.. django-admin:: dumpdata <appname appname appname.Model ...>
+.. django-admin:: dumpdata
 
 Outputs to standard output all data in the database associated with the named
 application(s).
@@ -215,18 +214,17 @@ directives::
 
     django-admin.py dumpdata --exclude=auth --exclude=contenttypes
 
-
 .. django-admin-option:: --format <fmt>
 
-    By default, ``dumpdata`` will format its output in JSON, but you can use the
-    ``--format`` option to specify another format. Currently supported formats
-    are listed in :ref:`serialization-formats`.
+By default, ``dumpdata`` will format its output in JSON, but you can use the
+``--format`` option to specify another format. Currently supported formats
+are listed in :ref:`serialization-formats`.
 
 .. django-admin-option:: --indent <num>
 
-    By default, ``dumpdata`` will output all data on a single line. This isn't
-    easy for humans to read, so you can use the ``--indent`` option to
-    pretty-print the output with a number of indentation spaces.
+By default, ``dumpdata`` will output all data on a single line. This isn't
+easy for humans to read, so you can use the ``--indent`` option to
+pretty-print the output with a number of indentation spaces.
 
 .. versionadded:: 1.1
 
@@ -239,22 +237,21 @@ model names.
 flush
 -----
 
-.. django-admin: flush
+.. django-admin:: flush
 
 Returns the database to the state it was in immediately after syncdb was
 executed. This means that all data will be removed from the database, any
 post-synchronization handlers will be re-executed, and the ``initial_data``
 fixture will be re-installed.
 
-.. django-admin-option:: --noinput
-
-    Use the ``--noinput`` option to suppress all user prompting, such as "Are
-    you sure?" confirmation messages. This is useful if ``django-admin.py`` is
-    being executed as an unattended, automated script.
+The :djadminopt:`--noinput` option may be provided to suppress all user
+prompts.
 
 inspectdb
 ---------
 
+.. django-admin:: inspectdb
+
 Introspects the database tables in the database pointed-to by the
 ``DATABASE_NAME`` setting and outputs a Django model module (a ``models.py``
 file) to standard output.
@@ -296,6 +293,8 @@ only works in PostgreSQL and with certain types of MySQL tables.
 loaddata <fixture fixture ...>
 ------------------------------
 
+.. django-admin:: loaddata
+
 Searches for and loads the contents of the named fixture into the database.
 
 What's a "fixture"?
@@ -382,6 +381,8 @@ installation will be aborted, and any data installed in the call to
 makemessages
 ------------
 
+.. django-admin:: makemessages
+
 .. versionchanged:: 1.0
    Before 1.0 this was the ``bin/make-messages.py`` command.
 
@@ -392,8 +393,7 @@ directory. After making changes to the messages files you need to compile them
 with ``compilemessages`` for use with the builtin gettext support. See the
 :ref:`i18n documentation <how-to-create-language-files>` for details.
 
---all
-~~~~~
+.. django-admin-option:: --all
 
 Use the ``--all`` or ``-a`` option to update the message files for all
 available languages.
@@ -402,8 +402,7 @@ Example usage::
 
     django-admin.py makemessages --all
 
---extension
-~~~~~~~~~~~
+.. django-admin-option:: --extension
 
 Use the ``--extension`` or ``-e`` option to specify a list of file extensions
 to examine (default: ".html").
@@ -416,17 +415,13 @@ Separate multiple extensions with commas or use -e or --extension multiple times
 
     django-admin.py makemessages --locale=de --extension=html,txt --extension xml
 
---locale
-~~~~~~~~
-
-Use the ``--locale`` or ``-l`` option to specify the locale to process.
+Use the :djadminopt:`--locale` option to specify the locale to process.
 
 Example usage::
 
     django-admin.py makemessages --locale=br_PT
 
---domain
-~~~~~~~~
+.. django-admin-option:: --domain
 
 Use the ``--domain`` or ``-d`` option to change the domain of the messages files.
 Currently supported:
@@ -434,23 +429,21 @@ Currently supported:
 	* ``django`` for all ``*.py`` and ``*.html`` files (default)
 	* ``djangojs`` for ``*.js`` files
 
-.. _django-admin-reset:
-
 reset <appname appname ...>
 ---------------------------
 
-Executes the equivalent of ``sqlreset`` for the given app name(s).
+.. django-admin:: reset
 
---noinput
-~~~~~~~~~
+Executes the equivalent of ``sqlreset`` for the given app name(s).
 
-Use the ``--noinput`` option to suppress all user prompting, such as
-"Are you sure?" confirmation messages. This is useful if ``django-admin.py``
-is being executed as an unattended, automated script.
+The :djadminopt:`--noinput` option may be provided to suppress all user
+prompts.
 
 runfcgi [options]
 -----------------
 
+.. django-admin:: runfcgi
+
 Starts a set of FastCGI processes suitable for use with any Web server that
 supports the FastCGI protocol. See the :ref:`FastCGI deployment documentation
 <howto-deployment-fastcgi>` for details. Requires the Python FastCGI module from
@@ -458,10 +451,10 @@ supports the FastCGI protocol. See the :ref:`FastCGI deployment documentation
 
 .. _flup: http://www.saddi.com/software/flup/
 
-runserver
----------
+runserver [port or ipaddr:port]
+-------------------------------
 
-.. django-admin:: runserver [port or ipaddr:port]
+.. django-admin:: runserver
 
 Starts a lightweight development Web server on the local machine. By default,
 the server runs on port 8000 on the IP address 127.0.0.1. You can pass in an
@@ -544,6 +537,8 @@ you want to configure Django to serve static media, read :ref:`howto-static-file
 shell
 -----
 
+.. django-admin:: shell
+
 Starts the Python interactive interpreter.
 
 Django will use IPython_, if it's installed. If you have IPython installed and
@@ -557,11 +552,15 @@ option, like so::
 sql <appname appname ...>
 -------------------------
 
+.. django-admin:: sql
+
 Prints the CREATE TABLE SQL statements for the given app name(s).
 
 sqlall <appname appname ...>
 ----------------------------
 
+.. django-admin:: sqlall
+
 Prints the CREATE TABLE and initial-data SQL statements for the given app name(s).
 
 Refer to the description of ``sqlcustom`` for an explanation of how to
@@ -570,11 +569,15 @@ specify initial data.
 sqlclear <appname appname ...>
 ------------------------------
 
+.. django-admin:: sqlclear
+
 Prints the DROP TABLE SQL statements for the given app name(s).
 
 sqlcustom <appname appname ...>
 -------------------------------
 
+.. django-admin:: sqlcustom
+
 Prints the custom SQL statements for the given app name(s).
 
 For each model in each specified app, this command looks for the file
@@ -594,21 +597,30 @@ Note that the order in which the SQL files are processed is undefined.
 sqlflush
 --------
 
-Prints the SQL statements that would be executed for the `flush`_ command.
+.. django-admin:: sqlflush
+
+Prints the SQL statements that would be executed for the :djadmin:`flush`
+command.
 
 sqlindexes <appname appname ...>
 --------------------------------
 
+.. django-admin:: sqlindexes
+
 Prints the CREATE INDEX SQL statements for the given app name(s).
 
 sqlreset <appname appname ...>
 ------------------------------
 
+.. django-admin:: sqlreset
+
 Prints the DROP TABLE SQL, then the CREATE TABLE SQL, for the given app name(s).
 
 sqlsequencereset <appname appname ...>
 --------------------------------------
 
+.. django-admin:: sqlsequencereset
+
 Prints the SQL statements for resetting sequences for the given app name(s).
 
 Sequences are indexes used by some database engines to track the next available
@@ -620,12 +632,16 @@ of sync with its automatically incremented field data.
 startapp <appname>
 ------------------
 
+.. django-admin:: startapp
+
 Creates a Django app directory structure for the given app name in the current
 directory.
 
 startproject <projectname>
 --------------------------
 
+.. django-admin:: startproject
+
 Creates a Django project directory structure for the given project name in the
 current directory.
 
@@ -635,11 +651,11 @@ This command is disabled when the ``--settings`` option to
 situations, either omit the ``--settings`` option or unset
 ``DJANGO_SETTINGS_MODULE``.
 
-.. _django-admin-syncdb:
-
 syncdb
 ------
 
+.. django-admin:: syncdb
+
 Creates the database tables for all apps in ``INSTALLED_APPS`` whose tables
 have not already been created.
 
@@ -669,29 +685,22 @@ with an appropriate extension (e.g. ``json`` or ``xml``). See the
 documentation for ``loaddata`` for details on the specification of fixture
 data files.
 
---noinput
-~~~~~~~~~
+The :djadminopt:`--noinput` option may be provided to suppress all user
+prompts.
 
-Use the ``--noinput`` option to suppress all user prompting, such as
-"Are you sure?" confirmation messages. This is useful if ``django-admin.py``
-is being executed as an unattended, automated script.
+test <app or test identifier>
+-----------------------------
 
-test
-----
+.. django-admin:: test
 
 Runs tests for all installed models. See :ref:`topics-testing` for more
 information.
 
---noinput
-~~~~~~~~~
-
-Use the ``--noinput`` option to suppress all user prompting, such as
-"Are you sure?" confirmation messages. This is useful if ``django-admin.py``
-is being executed as an unattended, automated script.
-
 testserver <fixture fixture ...>
 --------------------------------
 
+.. django-admin:: testserver
+
 .. versionadded:: 1.0
 
 Runs a Django development server (as in ``runserver``) using data from the
@@ -727,8 +736,7 @@ Note that this server does *not* automatically detect changes to your Python
 source code (as ``runserver`` does). It does, however, detect changes to
 templates.
 
---addrport [port number or ipaddr:port]
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. django-admin-option:: --addrport [port number or ipaddr:port]
 
 Use ``--addrport`` to specify a different port, or IP address and port, from
 the default of 127.0.0.1:8000. This value follows exactly the same format and
@@ -752,6 +760,8 @@ To run on 1.2.3.4:7000 with a ``test`` fixture::
 validate
 --------
 
+.. django-admin:: validate
+
 Validates all installed models (according to the ``INSTALLED_APPS`` setting)
 and prints validation errors to standard output.
 
@@ -761,8 +771,7 @@ Default options
 Although some subcommands may allow their own custom options, every subcommand
 allows for the following options:
 
---pythonpath
-------------
+.. django-admin-option:: --pythonpath
 
 Example usage::
 
@@ -777,8 +786,7 @@ setting the Python path for you.
 
 .. _import search path: http://diveintopython.org/getting_to_know_python/everything_is_an_object.html
 
---settings
-----------
+.. django-admin-option:: --settings
 
 Example usage::
 
@@ -792,8 +800,7 @@ variable.
 Note that this option is unnecessary in ``manage.py``, because it uses
 ``settings.py`` from the current project by default.
 
---traceback
------------
+.. django-admin-option:: --traceback
 
 Example usage::
 
@@ -803,10 +810,7 @@ By default, ``django-admin.py`` will show a simple error message whenever an
 error occurs. If you specify ``--traceback``, ``django-admin.py``  will
 output a full stack trace whenever an exception is raised.
 
-.. _django-admin-verbosity:
-
---verbosity
------------
+.. django-admin-option:: --verbosity
 
 Example usage::
 
@@ -819,6 +823,23 @@ that ``django-admin.py`` should print to the console.
     * ``1`` means normal output (default).
     * ``2`` means verbose output.
 
+Common options
+==============
+
+The following options are not available on every commands, but they are
+common to a number of commands.
+
+.. django-admin-option:: --locale
+
+Use the ``--locale`` or ``-l`` option to specify the locale to process.
+If not provided all locales are processed.
+
+.. django-admin-option:: --noinput
+
+Use the ``--noinput`` option to suppress all user prompting, such as "Are
+you sure?" confirmation messages. This is useful if ``django-admin.py`` is
+being executed as an unattended, automated script.
+
 Extra niceties
 ==============
 
@@ -844,5 +865,4 @@ distribution. It enables tab-completion of ``django-admin.py`` and
       with ``sql``.
 
 
-
 See :ref:`howto-custom-management-commands` for how to add customized actions.
diff --git a/docs/ref/models/options.txt b/docs/ref/models/options.txt
index 9bf73f5b85..d74f8350e8 100644
--- a/docs/ref/models/options.txt
+++ b/docs/ref/models/options.txt
@@ -94,9 +94,8 @@ See the docs for :meth:`~django.db.models.QuerySet.latest` for more.
 .. versionadded:: 1.1
 
 Defaults to ``True``, meaning Django will create the appropriate database
-tables in :ref:`django-admin-syncdb` and remove them as part of a :ref:`reset
-<django-admin-reset>` management command. That is, Django *manages* the
-database tables' lifecycles.
+tables in :djadmin:`syncdb` and remove them as part of a :djadmin:`reset`
+management command. That is, Django *manages* the database tables' lifecycles.
 
 If ``False``, no database table creation or deletion operations will be
 performed for this model. This is useful if the model represents an existing
@@ -114,7 +113,7 @@ model handling are exactly the same as normal. This includes
        unmanaged model, then the intermediate table for the many-to-many join
        will also not be created. However, a the intermediary table between one
        managed and one unmanaged model *will* be created.
-       
+
        If you need to change this default behavior, create the intermediary
        table as an explicit model (with ``managed`` set as needed) and use the
        :attr:`ManyToManyField.through` attribute to make the relation use your
diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt
index 8266224c39..20591311be 100644
--- a/docs/ref/templates/builtins.txt
+++ b/docs/ref/templates/builtins.txt
@@ -51,6 +51,18 @@ comment
 
 Ignore everything between ``{% comment %}`` and ``{% endcomment %}``
 
+.. templatetag:: csrf_token
+
+csrf_token
+~~~~~~~~~~
+
+.. versionadded:: 1.1.2
+
+In the Django 1.1.X series, this is a no-op tag that returns an empty string for
+future compatibility purposes.  In Django 1.2 and later, it is used for CSRF
+protection, as described in the documentation for :ref:`Cross Site Request
+Forgeries <ref-contrib-csrf>`.
+
 .. templatetag:: cycle
 
 csrf_token