Fixed #981 -- documented the SQL initial data insert files.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@2942 bcc190cf-cafb-0310-a4f2-bffc1f526a37

2 files changed, 29 insertions, 0 deletions

diff --git a/docs/django-admin.txt b/docs/django-admin.txt
index b314366fee..d829f4d975 100644
--- a/docs/django-admin.txt
+++ b/docs/django-admin.txt
@@ -200,6 +200,9 @@ sqlall [appname appname ...]
 
 Prints the CREATE TABLE and initial-data SQL statements for the given appnames.
 
+Refer to the description of ``sqlinitialdata`` for an explanation of how to
+specify seed data.
+
 sqlclear [appname appname ...]
 --------------------------------------
 
@@ -215,6 +218,14 @@ sqlinitialdata [appname appname ...]
 
 Prints the initial INSERT SQL statements for the given appnames.
 
+This command will read any files under ``<appname>/sql/`` that have the same
+name as the lower-cased version of a model name (so if your app includes a
+model called ``Poll``, the file ``poll.sql`` will be read). These files are
+expected to be valid SQL files and their contents are piped into the database
+after all of the models' table creation statements have been executed. This
+can be used to populate the tables with any necessary initial records or test
+data.
+
 sqlreset [appname appname ...]
 --------------------------------------
 
diff --git a/docs/model-api.txt b/docs/model-api.txt
index 6d6249ee88..de971f7e74 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -1631,3 +1631,21 @@ read, in part::
         'mysite.myapp',
         #...
     )
+
+Seeding models with initial data
+================================
+
+Sometimes, once the database tables for a model are created, you will want to
+populate them with some default records or perhaps some testing data. For each
+model you have like this, create a file named after the lower-cased version of
+the model's name, with an extension of ``.sql``. Put this file in a directory
+called ``sql/`` under your application directory (so, ``myapp/sql/poll.sql``
+for ``Poll`` model in the ``myapp`` application).
+
+This file should contain valid SQL statements that can be executed to create
+the initial data you would like to insert. These files are read by the
+``sqlinitialdata``, ``sqlreset``, ``sqlall`` and ``reset`` commands in
+``manage.py``. Refer to the `manage.py documentation`_ for more
+information.
+
+.. _`manage.py documentation`: http://www.djangoproject.com/documentation/django_admin/#sqlinitialdata-appname-appname