newforms-admin: Merged from trunk up to [7377].

git-svn-id: http://code.djangoproject.com/svn/django/branches/newforms-admin@7378 bcc190cf-cafb-0310-a4f2-bffc1f526a37

13 files changed, 390 insertions, 43 deletions

diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000000..f79d4299d5
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,68 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html web htmlhelp latex changes linkcheck
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html      to make standalone HTML files"
+	@echo "  web       to make files usable by Sphinx.web"
+	@echo "  htmlhelp  to make HTML files and a HTML help project"
+	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  changes   to make an overview over all changed/added/deprecated items"
+	@echo "  linkcheck to check all external links for integrity"
+
+clean:
+	-rm -rf _build/*
+
+html:
+	mkdir -p _build/html _build/doctrees
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html
+	@echo
+	@echo "Build finished. The HTML pages are in _build/html."
+
+web:
+	mkdir -p _build/web _build/doctrees
+	$(SPHINXBUILD) -b web $(ALLSPHINXOPTS) _build/web
+	@echo
+	@echo "Build finished; now you can run"
+	@echo "  python -m sphinx.web _build/web"
+	@echo "to start the server."
+
+htmlhelp:
+	mkdir -p _build/htmlhelp _build/doctrees
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in _build/htmlhelp."
+
+latex:
+	mkdir -p _build/latex _build/doctrees
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in _build/latex."
+	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
+	      "run these through (pdf)latex."
+
+changes:
+	mkdir -p _build/changes _build/doctrees
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes
+	@echo
+	@echo "The overview file is in _build/changes."
+
+linkcheck:
+	mkdir -p _build/linkcheck _build/doctrees
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in _build/linkcheck/output.txt."
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000000..0ced57d57b
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,132 @@
+# -*- coding: utf-8 -*-
+#
+# Django documentation build configuration file, created by
+# sphinx-quickstart on Thu Mar 27 09:06:53 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default value; values that are commented out
+# serve to show the default value.
+
+import sys
+
+# If your extensions are in another directory, add it here.
+#sys.path.append('some/directory')
+
+# General configuration
+# ---------------------
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+#extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = []
+
+# The suffix of source filenames.
+source_suffix = '.txt'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General substitutions.
+project = 'Django'
+copyright = '2008, Django Software Foundation'
+
+# The default replacements for |version| and |release|, also used in various
+# other places throughout the built documents.
+#
+# The short X.Y version.
+version = 'SVN'
+# The full version, including alpha/beta/rc tags.
+release = version
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = False
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# Options for HTML output
+# -----------------------
+
+# The style sheet to use for HTML and HTML Help pages. A file of that name
+# must exist either in Sphinx' static/ path, or in one of the custom paths
+# given in html_static_path.
+html_style = 'default.css'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+html_use_smartypants = True
+
+# Content template for the index page.
+#html_index = ''
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_use_modindex = True
+
+# If true, the reST sources are included in the HTML build as _sources/<name>.
+html_copy_source = True
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Djangodoc'
+
+
+# Options for LaTeX output
+# ------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+#latex_documents = []
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True
diff --git a/docs/db-api.txt b/docs/db-api.txt
index e9b5c05f6b..f8ed16988e 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -1306,9 +1306,6 @@ SQL equivalents::
 Using raw strings (e.g., ``r'foo'`` instead of ``'foo'``) for passing in the
 regular expression syntax is recommended.
 
-Regular expression matching is not supported on the ``ado_mssql`` backend.
-It will raise a ``NotImplementedError`` at runtime.
-
 iregex
 ~~~~~~
 
diff --git a/docs/i18n.txt b/docs/i18n.txt
index 8da19cd242..d6c86e1c9d 100644
--- a/docs/i18n.txt
+++ b/docs/i18n.txt
@@ -338,7 +338,7 @@ Django offers many utility functions (particularly in ``django.utils``) that
 take a string as their first argument and do something to that string. These
 functions are used by template filters as well as directly in other code.
 
-If you write your own similar functions and deal with translations, you'll 
+If you write your own similar functions and deal with translations, you'll
 face the problem of what to do when the first argument is a lazy translation
 object. You don't want to convert it to a string immediately, because you might
 be using this function outside of a view (and hence the current thread's locale
@@ -789,7 +789,7 @@ JavaScript that uses strings from different applications.
 You can make the view dynamic by putting the packages into the URL pattern::
 
     urlpatterns = patterns('',
-        (r'^jsi18n/(?P<packages>\S+?)/$, 'django.views.i18n.javascript_catalog'),
+        (r'^jsi18n/(?P<packages>\S+?)/$', 'django.views.i18n.javascript_catalog'),
     )
 
 With this, you specify the packages as a list of package names delimited by '+'
@@ -811,24 +811,47 @@ interface to access it::
 
     document.write(gettext('this is to be translated'));
 
-There even is a ``ungettext`` interface and a string interpolation function::
+There is also an ``ngettext`` interface::
 
-    d = {
-        count: 10
-    };
-    s = interpolate(ungettext('this is %(count)s object', 'this are %(count)s objects', d.count), d);
+    var object_cnt = 1 // or 0, or 2, or 3, ...
+    s = ngettext('literal for the singular case',
+            'literal for the plural case', object_cnt);
 
-The ``interpolate`` function supports both positional interpolation and named
-interpolation. So the above could have been written as::
+and even a string interpolation function::
 
-    s = interpolate(ungettext('this is %s object', 'this are %s objects', 11), [11]);
+    function interpolate(fmt, obj, named);
 
-The interpolation syntax is borrowed from Python. You shouldn't go over the top
-with string interpolation, though: this is still JavaScript, so the code will
-have to do repeated regular-expression substitutions. This isn't as fast as
-string interpolation  in Python, so keep it to those cases where you really
-need it (for example, in conjunction with ``ungettext`` to produce proper
-pluralizations).
+The interpolation syntax is borrowed from Python, so the ``interpolate``
+function supports both positional and named interpolation:
+
+    * Positional interpolation: ``obj`` contains a JavaScript Array object
+      whose elements values are then sequentially interpolated in their
+      corresponding ``fmt`` placeholders in the same order they appear.
+      For example::
+
+        fmts = ngettext('There is %s object. Remaining: %s',
+                'There are %s objects. Remaining: %s', 11);
+        s = interpolate(fmts, [11, 20]);
+        // s is 'There are 11 objects. Remaining: 20'
+
+    * Named interpolation: This mode is selected by passing the optional
+      boolean ``named`` parameter as true. ``obj`` contains a JavaScript
+      object or associative array. For example::
+
+        d = {
+            count: 10
+            total: 50
+        };
+
+        fmts = ngettext('Total: %(total)s, there is %(count)s object',
+        'there are %(count)s of a total of %(total)s objects', d.count);
+        s = interpolate(fmts, d, true);
+
+You shouldn't go over the top with string interpolation, though: this is still
+JavaScript, so the code has to make repeated regular-expression substitutions.
+This isn't as fast as string interpolation in Python, so keep it to those
+cases where you really need it (for example, in conjunction with ``ngettext``
+to produce proper pluralizations).
 
 Creating JavaScript translation catalogs
 ----------------------------------------
diff --git a/docs/index.txt b/docs/index.txt
new file mode 100644
index 0000000000..385ada455c
--- /dev/null
+++ b/docs/index.txt
@@ -0,0 +1,128 @@
+====================
+Django Documentation
+====================
+
+The essential documentation
+===========================
+
+If you're new to Django, make sure to read the following documentation in
+order.. The rest (in the "reference" section below) can be ready in any order as
+you need various functionality.
+
+.. toctree::
+   :maxdepth: 1
+   
+   overview
+   install
+   tutorial01
+   tutorial02
+   tutorial03
+   tutorial04
+   faq
+   documentation
+   
+Reference
+=========
+
+.. toctree::
+   :maxdepth: 1
+   
+   django-admin
+   model-api
+   db-api
+   transactions
+   templates
+   templates_python
+   newforms
+   modelforms
+   testing
+   sessions
+   cache
+   settings
+   url_dispatch
+   request_response
+   generic_views
+   authentication
+   shortcuts
+   unicode
+   pagination
+   serialization
+   i18n
+   middleware
+   custom_model_fields
+   databases
+   
+``django.contrib`` add-ons
+--------------------------
+
+.. toctree::
+   :maxdepth: 1
+   
+   add_ons
+   contenttypes
+   csrf
+   databrowse
+   flatpages
+   form_preview
+   form_wizard
+   localflavor
+   redirects
+   sites
+   sitemaps
+   syndication_feeds
+   webdesign
+   
+Deployment
+----------
+
+.. toctree::
+   :maxdepth: 1
+
+   modpython
+   fastcgi
+    
+Solving specific problems
+-------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   apache_auth
+   static_files
+   email
+   legacy_databases
+   outputting_pdf
+   outputting_csv
+    
+Et cetera
+---------
+
+.. toctree::
+   :maxdepth: 1
+
+   design_philosophies
+   contributing
+   admin_css
+   api_stability
+
+Release notes
+-------------
+
+.. toctree::
+   :maxdepth: 1
+
+   release_notes_0.96
+   release_notes_0.95
+
+Also see the list of `backwards-incompatible changes`__ for changes made between
+releases.
+
+__ http://code.djangoproject.com/wiki/BackwardsIncompatibleChanges
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
diff --git a/docs/install.txt b/docs/install.txt
index 341c4280e8..bfe85fff8a 100644
--- a/docs/install.txt
+++ b/docs/install.txt
@@ -172,11 +172,11 @@ Installing the development version
     If you decide to use the latest development version of Django,
     you'll want to pay close attention to `the development timeline`_,
     and you'll want to keep an eye on `the list of
-    backwards-incompatible changes`_; this will help you stay on top
+    backwards-incompatible changes`_. This will help you stay on top
     of any new features you might want to use, as well as any changes
-    you'll need to make to your code when updating your copy of Django
-    (for stable releases, any necessary changes are documented in the
-    release notes).
+    you'll need to make to your code when updating your copy of Django.
+    (For stable releases, any necessary changes are documented in the
+    release notes.)
 
 .. _the development timeline: http://code.djangoproject.com/timeline
 .. _the list of backwards-incompatible changes: http://code.djangoproject.com/wiki/BackwardsIncompatibleChanges
diff --git a/docs/modelforms.txt b/docs/modelforms.txt
index 05f9b1b3d4..554aeb7ea0 100644
--- a/docs/modelforms.txt
+++ b/docs/modelforms.txt
@@ -236,7 +236,7 @@ works exactly the same way as any other ``newforms`` form. For
 example, the ``is_valid()`` method is used to check for validity, the
 ``is_multipart()`` method is used to determine whether a form requires
 multipart file upload (and hence whether ``request.FILES`` must be
-passed to the form), etc.; see `the standard newforms documentation`_
+passed to the form), etc. See `the standard newforms documentation`_
 for more information.
 
 .. _the standard newforms documentation: ../newforms/
diff --git a/docs/request_response.txt b/docs/request_response.txt
index 0e0f046a2d..a4f03b9185 100644
--- a/docs/request_response.txt
+++ b/docs/request_response.txt
@@ -143,14 +143,13 @@ All attributes except ``session`` should be considered read-only.
 
 ``urlconf``
     Not defined by Django itself, but will be read if other code
-    (e.g., a custom middleware class) sets it; when present, this will
-    be used as the root URLConf for the current request, overriding
+    (e.g., a custom middleware class) sets it. When present, this will
+    be used as the root URLconf for the current request, overriding
     the ``ROOT_URLCONF`` setting. See `How Django processes a
     request`_ for details.
 
 .. _How Django processes a request: ../url_dispatch/#how-django-processes-a-request
 
-
 Methods
 -------
 
@@ -202,19 +201,19 @@ Methods
 ``is_ajax()``
    **New in Django development version**
 
-   Returns ``True`` if the request was made via an XMLHttpRequest by checking
-   the ``HTTP_X_REQUESTED_WITH`` header for the string *'XMLHttpRequest'*. The
-   following major Javascript libraries all send this header:
+   Returns ``True`` if the request was made via an ``XMLHttpRequest``, by checking
+   the ``HTTP_X_REQUESTED_WITH`` header for the string ``'XMLHttpRequest'``. The
+   following major JavaScript libraries all send this header:
 
-   * jQuery
-   * Dojo
-   * MochiKit
-   * MooTools
-   * Prototype
-   * YUI
+       * jQuery
+       * Dojo
+       * MochiKit
+       * MooTools
+       * Prototype
+       * YUI
 
-   If you write your own XMLHttpRequest call (on the browser side), you will
-   have to set this header manually to use this method.
+   If you write your own XMLHttpRequest call (on the browser side), you'll
+   have to set this header manually if you want ``is_ajax()`` to work.
 
 QueryDict objects
 -----------------
diff --git a/docs/settings.txt b/docs/settings.txt
index fb2e04f1ea..5aee19102b 100644
--- a/docs/settings.txt
+++ b/docs/settings.txt
@@ -279,7 +279,7 @@ Default: ``''`` (Empty string)
 
 The database backend to use. The build-in database backends are
 ``'postgresql_psycopg2'``, ``'postgresql'``, ``'mysql'``, ``'mysql_old'``,
-``'sqlite3'``, ``'oracle'``, or ``'ado_mssql'``.
+``'sqlite3'`` and ``'oracle'``.
 
 In the Django development version, you can use a database backend that doesn't
 ship with Django by setting ``DATABASE_ENGINE`` to a fully-qualified path (i.e.
diff --git a/docs/syndication_feeds.txt b/docs/syndication_feeds.txt
index f86acfe54d..6a603c4e54 100644
--- a/docs/syndication_feeds.txt
+++ b/docs/syndication_feeds.txt
@@ -250,7 +250,7 @@ request to the URL ``/rss/beats/0613/``:
       will be an empty list. In our example, ``len(bits) != 1`` and an
       ``ObjectDoesNotExist`` exception will be raised, so ``/rss/beats/`` will
       generate a 404 page. But you can handle this case however you like.  For
-      example you could generate a combined feed for all beats.
+      example, you could generate a combined feed for all beats.
 
     * To generate the feed's ``<title>``, ``<link>`` and ``<description>``,
       Django uses the ``title()``, ``link()`` and ``description()`` methods. In
diff --git a/docs/testing.txt b/docs/testing.txt
index 54b8ba9ae6..0ff3cce3d9 100644
--- a/docs/testing.txt
+++ b/docs/testing.txt
@@ -80,7 +80,7 @@ read Python's official documentation for the details.
 .. admonition:: What's a **docstring**?
 
     A good explanation of docstrings (and some guidelines for using them
-    effectively) can be found in :PEP:`257`:
+    effectively) can be found in :pep:`257`:
 
         A docstring is a string literal that occurs as the first statement in
         a module, function, class, or method definition.  Such a docstring
diff --git a/docs/tutorial04.txt b/docs/tutorial04.txt
index 473fba1ef8..f09f08ce56 100644
--- a/docs/tutorial04.txt
+++ b/docs/tutorial04.txt
@@ -39,7 +39,7 @@ A quick rundown:
       Django; it's just good Web development practice.
     
     * ``forloop.counter`` indicates how many times the ``for`` tag has
-      gone through its loop; for more information, see `the
+      gone through its loop. For more information, see `the
       documentation for the "for" tag`_.
 
 .. _the documentation for the "for" tag: ../templates/#for
diff --git a/docs/url_dispatch.txt b/docs/url_dispatch.txt
index 053ee954a3..28f15289a9 100644
--- a/docs/url_dispatch.txt
+++ b/docs/url_dispatch.txt
@@ -32,7 +32,7 @@ How Django processes a request
 When a user requests a page from your Django-powered site, this is the
 algorithm the system follows to determine which Python code to execute:
 
-    1. Django determines the root URLConf module to use; ordinarily
+    1. Django determines the root URLconf module to use. Ordinarily,
        this is the value of the ``ROOT_URLCONF`` setting in your
        `settings file`_, but if the incoming ``HttpRequest`` object
        has an attribute called ``urlconf``, its value will be used in