[soc2009/multidb] Corrected some markup problems in the release notes and added deprecation notes. Patch from Russell Keith-Magee.

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

docs/internals/deprecation.txt

@@ -26,7 +26,14 @@ their deprecation, as per the :ref:`Django deprecation policy
           class in favor of a generic E-mail backend API.
 
         * The many to many SQL generation functions on the database backends
-          will be removed.  These have been deprecated since the 1.2 release.
+          will be removed.
+
+        * The ability to use the ``DATABASE_*`` family of top-level settings to
+          define database connections will be removed.
+
+        * The ability to use shorthand notation to specify a database backend
+          (i.e., ``sqlite3`` instead of ``django.db.backends.sqlite3``) will be
+          removed.
 
     * 2.0
         * ``django.views.defaults.shortcut()``. This function has been moved

docs/ref/settings.txt

@@ -208,6 +208,7 @@ any number of additional databases may also be specified.
 
 The simplest possible settings file is for a single-database setup using
 SQLite. This can be configured using the following::
+
     DATABASES = {
         'default': {
             'BACKEND': 'django.db.backends.sqlite3',
@@ -1334,6 +1335,8 @@ DATABASE_ENGINE
    This setting has been replaced by :setting:`ENGINE` in
    :setting:`DATABASES`.
 
+.. setting:: DATABASE_HOST
+
 DATABASE_HOST
 -------------
 
@@ -1341,6 +1344,8 @@ DATABASE_HOST
    This setting has been replaced by :setting:`HOST` in
    :setting:`DATABASES`.
 
+.. setting:: DATABASE_NAME
+
 DATABASE_NAME
 -------------
 
@@ -1348,6 +1353,8 @@ DATABASE_NAME
    This setting has been replaced by :setting:`NAME` in
    :setting:`DATABASES`.
 
+.. setting:: DATABASE_OPTIONS
+
 DATABASE_OPTIONS
 ----------------
 
@@ -1355,6 +1362,8 @@ DATABASE_OPTIONS
    This setting has been replaced by :setting:`OPTIONS` in
    :setting:`DATABASES`.
 
+.. setting:: DATABASE_PASSWORD
+
 DATABASE_PASSWORD
 -----------------
 
@@ -1362,6 +1371,8 @@ DATABASE_PASSWORD
    This setting has been replaced by :setting:`PASSWORD` in
    :setting:`DATABASES`.
 
+.. setting:: DATABASE_PORT
+
 DATABASE_PORT
 -------------
 
@@ -1369,6 +1380,8 @@ DATABASE_PORT
    This setting has been replaced by :setting:`PORT` in
    :setting:`DATABASES`.
 
+.. setting:: DATABASE_USER
+
 DATABASE_USER
 -------------
 
@@ -1376,6 +1389,8 @@ DATABASE_USER
    This setting has been replaced by :setting:`USER` in
    :setting:`DATABASES`.
 
+.. setting:: TEST_DATABASE_CHARSET
+
 TEST_DATABASE_CHARSET
 ---------------------
 
@@ -1383,6 +1398,8 @@ TEST_DATABASE_CHARSET
    This setting has been replaced by :setting:`TEST_CHARSET` in
    :setting:`DATABASES`.
 
+.. setting:: TEST_DATABASE_COLLATION
+
 TEST_DATABASE_COLLATION
 -----------------------
 
@@ -1390,6 +1407,8 @@ TEST_DATABASE_COLLATION
    This setting has been replaced by :setting:`TEST_COLLATION` in
    :setting:`DATABASES`.
 
+.. setting:: TEST_DATABASE_NAME
+
 TEST_DATABASE_NAME
 ------------------
 

docs/releases/1.2.txt

@@ -74,8 +74,13 @@ Prior to Django 1.1, Django used a number of settings to control access to a
 single database. Django 1.2 introduces support for multiple databases, and as
 a result, the way you define database settings has changed.
 
-Previously, there were a number of ``DATABASE_`` settings at the top level of
+Any existing Django settings file will continue to work as expected until
-your settings file. For example::
+Django 1.4. Old-style database settings will be automatically translated to
+the new-style format.
+
+In the old-style (pre 1.2) format, there were a number of
+``DATABASE_`` settings at the top level of your settings file. For
+example::
 
     DATABASE_NAME = 'test_db'
     DATABASE_BACKEND = 'postgresl_psycopg2'
@@ -83,11 +88,11 @@ your settings file. For example::
     DATABASE_PASSWORD = 's3krit'
 
 These settings are now contained inside a dictionary named
-``DATABASES``. Each item in the dictionary corresponds to a single
+:setting:`DATABASES`. Each item in the dictionary corresponds to a
-database connection, with the name ``default`` describing the default
+single database connection, with the name ``'default'`` describing the
-database connection. The setting names have also been shortened to
+default database connection. The setting names have also been
-reflect the fact that they are stored in a dictionary. The sample
+shortened to reflect the fact that they are stored in a dictionary.
-settings given previously would now be stored using::
+The sample settings given previously would now be stored using::
 
     DATABASES = {
         'default': {
@@ -95,31 +100,34 @@ settings given previously would now be stored using::
             'BACKEND': 'django.db.backends.postgresl_psycopg2',
             'USER': 'myusername',
             'PASSWORD': 's3krit',
+        }
     }
 
 This affects the following settings:
 
-    Old setting                                New Setting
+    =========================================  ==========================
-    =========================================  ===========
+     Old setting                                New Setting
-    :setting:`DATABASE_ENGINE`                 ENGINE
+    =========================================  ==========================
-    :setting:`DATABASE_HOST`                   HOST
+    :setting:`DATABASE_ENGINE`                 :setting:`ENGINE`
-    :setting:`DATABASE_NAME`                   NAME
+    :setting:`DATABASE_HOST`                   :setting:`HOST`
-    :setting:`DATABASE_OPTIONS`                OPTIONS
+    :setting:`DATABASE_NAME`                   :setting:`NAME`
-    :setting:`DATABASE_PASSWORD`               PASSWORD
+    :setting:`DATABASE_OPTIONS`                :setting:`OPTIONS`
-    :setting:`DATABASE_PORT`                   PORT
+    :setting:`DATABASE_PASSWORD`               :setting:`PASSWORD`
-    :setting:`DATABASE_USER`                   USER
+    :setting:`DATABASE_PORT`                   :setting:`PORT`
-    :setting:`TEST_DATABASE_CHARSET`           TEST_CHARSET
+    :setting:`DATABASE_USER`                   :setting:`USER`
-    :setting:`TEST_DATABASE_COLLATION`         TEST_COLLATION
+    :setting:`TEST_DATABASE_CHARSET`           :setting:`TEST_CHARSET`
-    :setting:`TEST_DATABASE_NAME`              TEST_NAME
+    :setting:`TEST_DATABASE_COLLATION`         :setting:`TEST_COLLATION`
+    :setting:`TEST_DATABASE_NAME`              :setting:`TEST_NAME`
+    =========================================  ==========================
 
 These changes are also required if you have manually created a database
-connection using
+connection using ``DatabaseWrapper()`` from your database backend of choice.
 
 In addition to the change in structure, Django 1.2 removes the special
 handling for the built-in database backends. All database backends
-must now be specified by a fully qualified class name (i.e.,
+must now be specified by a fully qualified module name (i.e.,
 ``django.db.backends.postgresl_psycopg2``, rather than just
-``postgresql_psycopg2``)
+``postgresql_psycopg2``).
 
 ``__dict__`` on Model instances
 -------------------------------
@@ -177,7 +185,7 @@ Support for multiple databases
 ------------------------------
 
 Django 1.2 adds the ability to use :ref:`more than one database
-<topics-db-multi-db>`in your Django project. Queries can be
+<topics-db-multi-db>` in your Django project. Queries can be
 issued at a specific database with the `using()` method on
 querysets; individual objects can be saved to a specific database
 by providing a ``using`` argument when you save the instance.