Documented django.setup().

Thanks Eric Holscher and Tim Graham for the review.

2 files changed, 66 insertions, 5 deletions

diff --git a/docs/ref/applications.txt b/docs/ref/applications.txt
index 0a7a0c991d..829e273aa9 100644
--- a/docs/ref/applications.txt
+++ b/docs/ref/applications.txt
@@ -307,13 +307,71 @@ Application registry
     :exc:`ValueError` when called with a single argument that doesn't contain
     exactly one dot.
 
+Initialization process
+======================
+
+How applications are loaded
+---------------------------
+
+When Django starts, :func:`django.setup()` is responsible for populating the
+application registry.
+
+.. currentmodule:: django
+
+.. function:: setup()
+
+    Configures Django by:
+
+    * Loading the settings.
+    * Setting up logging.
+    * Initializing the application registry.
+
+    This function is called automatically:
+
+    * When running an HTTP server via Django's WSGI support.
+    * When invoking a management command.
+
+    It must be called explicitly in other cases, for instance in plain Python
+    scripts.
+
+.. currentmodule:: django.apps
+
+The application registry is initialized in three stages. At each stage, Django
+processes all applications in the order of :setting:`INSTALLED_APPS`.
+
+#. First Django imports each item in :setting:`INSTALLED_APPS`.
+
+   If it's an application configuration class, Django imports the root package
+   of the application, defined by its :attr:`~AppConfig.name` attribute. If
+   it's a Python package, Django creates a default application configuration.
+
+   *At this stage, your code shouldn't import any models!*
+
+   In other words, your applications' root packages and the modules that
+   define your application configuration classes shouldn't import any models,
+   even indirectly.
+
+   Strictly speaking, Django allows importing models once their application
+   configuration is loaded. However, in order to avoid needless constraints on
+   the order of :setting:`INSTALLED_APPS`, it's strongly recommended not
+   import any models at this stage.
+
+#. Then Django attempts to import the ``models`` submodule of each application,
+   if there is one.
+
+   You must define or import all models in your application's ``models.py`` or
+   ``models/__init__.py``. Otherwise, the application registry may not be fully
+   populated at this point, which could cause the ORM to malfunction.
+
+#. Finally Django runs the :meth:`~AppConfig.ready()` method of each application
+   configuration.
+
 .. _applications-troubleshooting:
 
 Troubleshooting
-===============
+---------------
 
-Django loads application configurations and models as soon as it starts. Here
-are some common problems you may encounter:
+Here are some common problems that you may encounter during initialization:
 
 * ``RuntimeError: App registry isn't ready yet.`` This happens when importing
   an application configuration or a models module triggers code that depends
@@ -334,6 +392,9 @@ are some common problems you may encounter:
   the :setting:`AUTH_USER_MODEL` setting to reference the User model at import
   time.
 
+  This exception also happens if you forget to call :func:`django.setup()` in
+  a standalone Python script.
+
 * ``ImportError: cannot import name ...`` This happens if the import sequence
   ends up in a loop.
 
diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt
index 945f0b4409..7cf5e4ff18 100644
--- a/docs/ref/django-admin.txt
+++ b/docs/ref/django-admin.txt
@@ -14,11 +14,11 @@ two things for you before delegating to ``django-admin.py``:
 * It sets the :envvar:`DJANGO_SETTINGS_MODULE` environment variable so that
   it points to your project's ``settings.py`` file.
 
-* It calls ``django.setup()`` to initialize various internals of Django.
+* It calls :func:`django.setup()` to initialize various internals of Django.
 
 .. versionadded:: 1.7
 
-    ``django.setup()`` didn't exist in previous versions of Django.
+    :func:`django.setup()` didn't exist in previous versions of Django.
 
 The ``django-admin.py`` script should be on your system path if you installed
 Django via its ``setup.py`` utility. If it's not on your path, you can find it