r10928@kevin-kubasiks-macbook: kkubasik | 2009-06-26 03:44:58 -0600

[gsoc2009-testing] Merging in the latest changes from trunk. Mostly just documentation


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

django/contrib/admindocs/templates/admin_doc/model_index.html

@@ -36,7 +36,7 @@
 <ul>
 {% regroup models by app_label as grouped_models %}
 {% for group in grouped_models %}
-    <li><a href="#{{ group.grouper }}">{{ group.grouper|capfirst }}</a></li>
+    <li><a href="#app-{{ group.grouper }}">{{ group.grouper|capfirst }}</a></li>
 {% endfor %}
 </ul>
 </div>

docs/ref/contrib/admin/index.txt

@@ -667,6 +667,43 @@ Controls where on the page the actions bar appears. By default, the admin
 changelist displays actions at the top of the page (``actions_on_top = True;
 actions_on_bottom = False``).
 
+.. attribute:: ModelAdmin.change_list_template
+
+Path to a custom template that will be used by the model objects "change list"
+view. Templates can override or extend base admin templates as described in
+`Overriding Admin Templates`_.
+
+If you don't specify this attribute, a default template shipped with Django
+that provides the standard appearance is used.
+
+.. attribute:: ModelAdmin.change_form_template
+
+Path to a custom template that will be used by both the model object creation
+and change views. Templates can override or extend base admin templates as
+described in `Overriding Admin Templates`_.
+
+If you don't specify this attribute, a default template shipped with Django
+that provides the standard appearance is used.
+
+.. attribute:: ModelAdmin.object_history_template
+
+Path to a custom template that will be used by the model object change history
+display view. Templates can override or extend base admin templates as
+described in `Overriding Admin Templates`_.
+
+If you don't specify this attribute, a default template shipped with Django
+that provides the standard appearance is used.
+
+.. attribute:: ModelAdmin.delete_confirmation_template
+
+Path to a custom template that will be used by the view responsible of showing
+the confirmation page when the user decides to delete one or more model
+objects. Templates can override or extend base admin templates as described in
+`Overriding Admin Templates`_.
+
+If you don't specify this attribute, a default template shipped with Django
+that provides the standard appearance is used.
+
 ``ModelAdmin`` methods
 ----------------------
 
@@ -762,6 +799,56 @@ return a subset of objects for this foreign key field based on the user::
 This uses the ``HttpRequest`` instance to filter the ``Car`` foreign key field
 to only the cars owned by the ``User`` instance.
 
+Other methods
+~~~~~~~~~~~~~
+
+.. method:: ModelAdmin.add_view(self, request, form_url='', extra_context=None)
+
+Django view for the model instance addition page. See note below.
+
+.. method:: ModelAdmin.change_view(self, request, object_id, extra_context=None)
+
+Django view for the model instance edition page. See note below.
+
+.. method:: ModelAdmin.changelist_view(self, request, extra_context=None)
+
+Django view for the model instances change list/actions page. See note below.
+
+.. method:: ModelAdmin.delete_view(self, request, object_id, extra_context=None)
+
+Django view for the model instance(s) deletion confirmation page. See note below.
+
+.. method:: ModelAdmin.history_view(self, request, object_id, extra_context=None)
+
+Django view for the page that shows the modification history for a given model
+instance.
+
+Unlike the hook-type ``ModelAdmin`` methods detailed in the previous section,
+these five methods are in reality designed to be invoked as Django views from
+the admin application URL dispatching handler to render the pages that deal
+with model instances CRUD operations. As a result, completely overriding these
+methods will significantly change the behavior of the admin application.
+
+One comon reason for overriding these methods is to augment the context data
+that is provided to the template that renders the view. In the following
+example, the change view is overridden so that the rendered template is
+provided some extra mapping data that would not otherwise be available::
+
+    class MyModelAdmin(admin.ModelAdmin):
+
+        # A template for a very customized change view:
+        change_form_template = 'admin/myapp/extras/openstreetmap_change_form.html'
+
+        def get_osm_info(self):
+            # ...
+
+        def change_view(self, request, object_id, extra_context=None):
+            my_context = {
+                'osm_data': self.get_osm_info(),
+            }
+            return super(MyModelAdmin, self).change_view(request, object_id,
+                extra_context=my_context))
+
 ``ModelAdmin`` media definitions
 --------------------------------
 
@@ -783,7 +870,7 @@ Adding custom validation to the admin
 -------------------------------------
 
 Adding custom validation of data in the admin is quite easy. The automatic admin
-interfaces reuses :mod:`django.forms`, and the ``ModelAdmin`` class gives you
+interface reuses :mod:`django.forms`, and the ``ModelAdmin`` class gives you
 the ability define your own form::
 
     class ArticleAdmin(admin.ModelAdmin):
@@ -803,7 +890,9 @@ any field::
 
 It is important you use a ``ModelForm`` here otherwise things can break. See the
 :ref:`forms <ref-forms-index>` documentation on :ref:`custom validation
-<ref-forms-validation>` for more information.
+<ref-forms-validation>` and, more specifically, the
+:ref:`model form validation notes <overriding-modelform-clean-method>` for more
+information.
 
 .. _admin-inlines:
 
@@ -1106,7 +1195,7 @@ directory, our link would appear on every model's change form.
 Templates which may be overridden per app or model
 --------------------------------------------------
 
-Not every template in ``contrib\admin\templates\admin`` may be overridden per
+Not every template in ``contrib/admin/templates/admin`` may be overridden per
 app or per model. The following can:
 
     * ``app_index.html``
@@ -1131,8 +1220,8 @@ Root and login templates
 ------------------------
 
 If you wish to change the index or login templates, you are better off creating
-your own ``AdminSite`` instance (see below), and changing the ``index_template``
+your own ``AdminSite`` instance (see below), and changing the :attr:`AdminSite.index_template`
-or ``login_template`` properties.
+or :attr:`AdminSite.login_template` properties.
 
 ``AdminSite`` objects
 =====================
@@ -1151,6 +1240,21 @@ or add anything you like. Then, simply create an instance of your
 Python class), and register your models and ``ModelAdmin`` subclasses
 with it instead of using the default.
 
+``AdminSite`` attributes
+------------------------
+
+.. attribute:: AdminSite.index_template
+
+Path to a custom template that will be used by the admin site main index view.
+Templates can override or extend base admin templates as described in
+`Overriding Admin Templates`_.
+
+.. attribute:: AdminSite.login_template
+
+Path to a custom template that will be used by the admin site login view.
+Templates can override or extend base admin templates as described in
+`Overriding Admin Templates`_.
+
 Hooking ``AdminSite`` instances into your URLconf
 -------------------------------------------------
 

docs/ref/databases.txt

@@ -251,7 +251,7 @@ Here's a sample configuration which uses a MySQL option file::
     DATABASE_OPTIONS = {
         'read_default_file': '/path/to/my.cnf',
     }
-    
+
     # my.cnf
     [client]
     database = DATABASE_NAME
@@ -445,10 +445,10 @@ If you're getting this error, you can solve it by:
     * Switching to another database backend. At a certain point SQLite becomes
       too "lite" for real-world applications, and these sorts of concurrency
       errors indicate you've reached that point.
-      
+
-    * Rewriting your code to reduce concurrency and ensure that database 
+    * Rewriting your code to reduce concurrency and ensure that database
       transactions are short-lived.
-      
+
     * Increase the default timeout value by setting the ``timeout`` database
       option option::
 
@@ -457,7 +457,7 @@ If you're getting this error, you can solve it by:
              "timeout": 20,
               # ...
           }
-      
+
       This will simply make SQLite wait a bit longer before throwing "database
       is locked" errors; it won't really do anything to solve them.
 
@@ -601,3 +601,28 @@ some limitations on the usage of such LOB columns in general:
     Oracle. A workaround to this is to keep ``TextField`` columns out of any
     models that you foresee performing ``distinct()`` queries on, and to
     include the ``TextField`` in a related model instead.
+
+.. _third-party-notes:
+
+Using a 3rd-party database backend
+==================================
+
+In addition to the officially supported databases, there are backends provided
+by 3rd parties that allow you to use other databases with Django:
+
+* `Sybase SQL Anywhere`_
+* `IBM DB2`_
+* `Microsoft SQL Server 2005`_
+* Firebird_
+* ODBC_
+
+The Django versions and ORM features supported by these unofficial backends
+vary considerably. Queries regarding the specific capabilities of these
+unofficial backends, along with any support queries, should be directed to
+the support channels provided by each 3rd party project.
+
+.. _Sybase SQL Anywhere: http://code.google.com/p/sqlany-django/
+.. _IBM DB2: http://code.google.com/p/ibm-db/
+.. _Microsoft SQL Server 2005: http://code.google.com/p/django-mssql/
+.. _Firebird: http://code.google.com/p/django-firebird/
+.. _ODBC: http://code.google.com/p/django-pyodbc/

docs/ref/models/querysets.txt

@@ -35,7 +35,7 @@ You can evaluate a ``QuerySet`` in the following ways:
 
     * **Slicing.** As explained in :ref:`limiting-querysets`, a ``QuerySet`` can
       be sliced, using Python's array-slicing syntax. Usually slicing a
-      ``QuerySet`` returns another (unevaluated ) ``QuerySet``, but Django will
+      ``QuerySet`` returns another (unevaluated) ``QuerySet``, but Django will
       execute the database query if you use the "step" parameter of slice
       syntax.
 

docs/topics/forms/modelforms.txt

@@ -397,16 +397,26 @@ to be rendered first, we could specify the following ``ModelForm``::
     ...         model = Book
     ...         fields = ['title', 'author']
 
+.. _overriding-modelform-clean-method:
 
 Overriding the clean() method
 -----------------------------
 
 You can override the ``clean()`` method on a model form to provide additional
-validation in the same way you can on a normal form. However, by default the
+validation in the same way you can on a normal form.
-``clean()`` method validates the uniqueness of fields that are marked as
+
-``unique``, ``unique_together`` or ``unique_for_date|month|year`` on the model.
+In this regard, model forms have two specific characteristics when compared to
-Therefore, if you would like to override the ``clean()`` method and maintain the
+forms:
-default validation, you must call the parent class's ``clean()`` method.
+
+By default the ``clean()`` method validates the uniqueness of fields that are
+marked as ``unique``, ``unique_together`` or ``unique_for_date|month|year`` on
+the model.  Therefore, if you would like to override the ``clean()`` method and
+maintain the default validation, you must call the parent class's ``clean()``
+method.
+
+Also, a model form instance bound to a model object will contain a
+``self.instance`` attribute that gives model form methods access to that
+specific model instance.
 
 Form inheritance
 ----------------

docs/topics/i18n.txt

@@ -978,15 +978,17 @@ message files (``.po``). Translation work itself just involves editing existing
 files of this type, but if you want to create your own message files, or want to
 test or compile a changed message file, you will need the ``gettext`` utilities:
 
-    * Download the following zip files from
+    * Download the following zip files from the GNOME servers
-      http://sourceforge.net/projects/gettext
+      http://ftp.gnome.org/pub/gnome/binaries/win32/dependencies/ or from one
+      of its mirrors_
 
-      * ``gettext-runtime-X.bin.woe32.zip``
+      * ``gettext-runtime-X.zip``
-      * ``gettext-tools-X.bin.woe32.zip``
+      * ``gettext-tools-X.zip``
-      * ``libiconv-X.bin.woe32.zip``
 
-    * Extract the 3 files in the same folder (i.e. ``C:\Program
+      ``X`` is the version number, we recomend using ``0.15`` or higher.
-      Files\gettext-utils``)
+
+    * Extract the contents of the ``bin\`` directories in both files to the
+      same folder on your system (i.e. ``C:\Program Files\gettext-utils``)
 
     * Update the system PATH:
 
@@ -995,6 +997,8 @@ test or compile a changed message file, you will need the ``gettext`` utilities:
       * Add ``;C:\Program Files\gettext-utils\bin`` at the end of the
         ``Variable value`` field
 
+.. _mirrors: http://ftp.gnome.org/pub/GNOME/MIRRORS
+
 You may also use ``gettext`` binaries you have obtained elsewhere, so long as
 the ``xgettext --version`` command works properly. Some version 0.14.4 binaries
 have been found to not support this command. Do not attempt to use Django

docs/topics/install.txt

@@ -61,13 +61,27 @@ for each platform.
 Get your database running
 =========================
 
-If you plan to use Django's database API functionality, you'll need to
+If you plan to use Django's database API functionality, you'll need to make
-make sure a database server is running. Django works with PostgreSQL_,
+sure a database server is running. Django supports many different database
-MySQL_, Oracle_ and SQLite_ (although SQLite doesn't require a separate server
+servers and is officially supported with PostgreSQL_, MySQL_, Oracle_ and
-to be running).
+SQLite_ (although SQLite doesn't require a separate server to be running).
 
-Additionally, you'll need to make sure your Python database bindings are
+In addition to the officially supported databases, there are backends provided
-installed.
+by 3rd parties that allow you to use other databases with Django:
+
+* `Sybase SQL Anywhere`_
+* `IBM DB2`_
+* `Microsoft SQL Server 2005`_
+* Firebird_
+* ODBC_
+
+The Django versions and ORM features supported by these unofficial backends
+vary considerably. Queries regarding the specific capabilities of these
+unofficial backends, along with any support queries, should be directed to the
+support channels provided by each 3rd party project.
+
+In addition to a database backend, you'll need to make sure your Python
+database bindings are installed.
 
 * If you're using PostgreSQL, you'll need the psycopg_ package. Django supports
   both version 1 and 2. (When you configure Django's database layer, specify
@@ -89,6 +103,9 @@ installed.
   :ref:`Oracle backend <oracle-notes>` for important information
   regarding supported versions of both Oracle and ``cx_Oracle``.
 
+* If you're using an unofficial 3rd party backend, please consult the
+  documentation provided for any additional requirements.
+
 If you plan to use Django's ``manage.py syncdb`` command to
 automatically create database tables for your models, you'll need to
 ensure that Django has permission to create and alter tables in the
@@ -111,7 +128,11 @@ Django will need permission to create a test database.
 .. _pysqlite: http://pysqlite.org/
 .. _cx_Oracle: http://cx-oracle.sourceforge.net/
 .. _Oracle: http://www.oracle.com/
-
+.. _Sybase SQL Anywhere: http://code.google.com/p/sqlany-django/
+.. _IBM DB2: http://code.google.com/p/ibm-db/
+.. _Microsoft SQL Server 2005: http://code.google.com/p/django-mssql/
+.. _Firebird: http://code.google.com/p/django-firebird/
+.. _ODBC: http://code.google.com/p/django-pyodbc/
 .. _removing-old-versions-of-django:
 
 Remove any old versions of Django