Fixed #21712 -- Moved autodiscover() to AdminConfig.ready().

Thanks Marc Tamlyn for the initial version of the patch.

3 files changed, 45 insertions, 16 deletions

diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt
index efd72f58db..12d64d427a 100644
--- a/docs/ref/contrib/admin/index.txt
+++ b/docs/ref/contrib/admin/index.txt
@@ -23,8 +23,12 @@ The admin is enabled in the default project template used by
 
 For reference, here are the requirements:
 
-1. Add ``'django.contrib.admin'`` to your :setting:`INSTALLED_APPS`
-   setting.
+1. Add ``'django.contrib.admin.apps.AdminConfig'`` to your
+   :setting:`INSTALLED_APPS` setting.
+
+   .. versionchanged:: 1.7
+
+       :setting:`INSTALLED_APPS` used to contain ``'django.contrib.admin'``.
 
 2. The admin has four dependencies - :mod:`django.contrib.auth`,
    :mod:`django.contrib.contenttypes`,
@@ -76,7 +80,7 @@ Other topics
 .. class:: ModelAdmin
 
     The ``ModelAdmin`` class is the representation of a model in the admin
-    interface. These are stored in a file named ``admin.py`` in your
+    interface. Usually, these are stored in a file named ``admin.py`` in your
     application. Let's take a look at a very simple example of
     the ``ModelAdmin``::
 
@@ -129,6 +133,36 @@ The register decorator
         class PersonAdmin(admin.ModelAdmin):
             pass
 
+Discovery of admin files
+------------------------
+
+The admin needs to be instructed to look for ``admin.py`` files in your project.
+The easiest solution is to put ``'django.contrib.admin.apps.AdminConfig'`` in
+your :setting:`INSTALLED_APPS` setting.
+
+.. class:: django.contrib.admin.apps.AdminConfig
+
+    .. versionadded:: 1.7
+
+    This class calls :func:`~django.contrib.admin.autodiscover()` when Django
+    starts.
+
+.. function:: django.contrib.admin.autodiscover
+
+    This function attempts to import an ``admin`` module in each installed
+    application. Such modules are expected to register models with the admin.
+
+    .. versionchanged:: 1.7
+
+        Previous versions of Django recommended calling this function directly
+        in the URLconf. :class:`~django.contrib.admin.apps.AdminConfig`
+        replaces that mechanism and is more robust.
+
+If you are using a custom ``AdminSite``, it is common to import all of the
+``ModelAdmin`` subclasses into your code and register them to the custom
+``AdminSite``. In that case, simply put ``'django.contrib.admin'`` in your
+:setting:`INSTALLED_APPS` setting, as you don't need autodiscovery.
+
 ``ModelAdmin`` options
 ----------------------
 
@@ -2377,15 +2411,10 @@ In this example, we register the default ``AdminSite`` instance
     from django.conf.urls import patterns, include
     from django.contrib import admin
 
-    admin.autodiscover()
-
     urlpatterns = patterns('',
         (r'^admin/', include(admin.site.urls)),
     )
 
-Above we used ``admin.autodiscover()`` to automatically load the
-:setting:`INSTALLED_APPS` admin.py modules.
-
 In this example, we register the ``AdminSite`` instance
 ``myproject.admin.admin_site`` at the URL ``/myadmin/`` ::
 
@@ -2397,9 +2426,11 @@ In this example, we register the ``AdminSite`` instance
         (r'^myadmin/', include(admin_site.urls)),
     )
 
-There is really no need to use autodiscover when using your own ``AdminSite``
-instance since you will likely be importing all the per-app admin.py modules
-in your ``myproject.admin`` module.
+Note that you don't need autodiscovery of ``admin`` modules when using your
+own ``AdminSite`` instance since you will likely be importing all the per-app
+``admin`` modules in your ``myproject.admin`` module. This means you likely do
+not need ``'django.contrib.admin.app.AdminConfig'`` in your
+:setting:`INSTALLED_APPS` and can just use ``'django.contrib.admin'``.
 
 Multiple admin sites in the same URLconf
 ----------------------------------------
diff --git a/docs/ref/contrib/gis/tutorial.txt b/docs/ref/contrib/gis/tutorial.txt
index 4081a11157..f3eeb64e59 100644
--- a/docs/ref/contrib/gis/tutorial.txt
+++ b/docs/ref/contrib/gis/tutorial.txt
@@ -115,7 +115,7 @@ In addition, modify the :setting:`INSTALLED_APPS` setting to include
 and ``world`` (your newly created application)::
 
     INSTALLED_APPS = (
-        'django.contrib.admin',
+        'django.contrib.admin.apps.AdminConfig',
         'django.contrib.auth',
         'django.contrib.contenttypes',
         'django.contrib.sessions',
@@ -734,8 +734,6 @@ Next, edit your ``urls.py`` in the ``geodjango`` application folder as follows::
     from django.conf.urls import patterns, url, include
     from django.contrib.gis import admin
 
-    admin.autodiscover()
-
     urlpatterns = patterns('',
         url(r'^admin/', include(admin.site.urls)),
     )
diff --git a/docs/ref/contrib/index.txt b/docs/ref/contrib/index.txt
index cd85b45487..3b57ba8c17 100644
--- a/docs/ref/contrib/index.txt
+++ b/docs/ref/contrib/index.txt
@@ -14,8 +14,8 @@ those packages have.
 
     For most of these add-ons -- specifically, the add-ons that include either
     models or template tags -- you'll need to add the package name (e.g.,
-    ``'django.contrib.admin'``) to your :setting:`INSTALLED_APPS` setting and
-    re-run ``manage.py migrate``.
+    ``'django.contrib.redirects'``) to your :setting:`INSTALLED_APPS` setting
+    and re-run ``manage.py migrate``.
 
 .. _"batteries included" philosophy: http://docs.python.org/tutorial/stdlib.html#batteries-included