Discourage relying on the automatic setup.

Author: aaugustin

docs/installation.rst

@@ -18,8 +18,8 @@ instead with the following command::
 
      $ pip install -e git+https://github.com/django-debug-toolbar/django-debug-toolbar.git#egg=django-debug-toolbar
 
-Quick setup
------------
+Prerequisites
+-------------
 
 Make sure that ``'django.contrib.staticfiles'`` is `set up properly
 <https://docs.djangoproject.com/en/stable/howto/static-files/>`_ and add
@@ -34,25 +34,35 @@ Make sure that ``'django.contrib.staticfiles'`` is `set up properly
 
     STATIC_URL = '/static/'
 
-For a simple Django project, that's all you need!
-
-The Debug Toolbar will automatically adjust a few settings when you start the
-development server, provided the ``DEBUG`` setting is ``True``.
-
 If you're upgrading from a previous version, you should review the
 :doc:`change log <changes>` and look for specific upgrade instructions.
 
-If the automatic setup doesn't work for your project, if you want to learn
-what it does, or if you prefer defining your settings explicitly, read below.
+Automatic setup
+---------------
+
+If you just add the Debug Toolbar to the ``INSTALLED_APPS`` setting as shown
+above, when the ``DEBUG`` setting is ``True``, the Debug Toolbar will attempt
+to patch your settings to configure itself automatically.
 
 .. warning::
 
+    The automatic setup is known to interfere with the start-up sequence of
+    some projects and to prevent them from loading or functioning properly.
+
+    **The explicit setup described below is recommended for all but the most
+    trivial projects. The automatic setup is kept for backwards-compatibility.**
+
+.. note::
+
     The automatic setup imports your project's URLconf in order to add the
-    Debug Toolbar's URLs. This may trigger circular imports, for instance when
-    the URLconf imports views that import models. If the development server
-    crashes with a long stack trace after hitting an :exc:`ImportError` or an
-    :exc:`~django.core.exceptions.ImproperlyConfigured` exception, follow the
-    explicit setup instructions.
+    Debug Toolbar's URLs. This is likely to trigger circular imports, for
+    instance when the URLconf imports views that import models, a pattern
+    found in almost every Django project.
+
+    If the development server crashes with a long stack trace after hitting an
+    :exc:`ImportError`, an :exc:`~django.apps.exceptions.AppRegistryNotReady`
+    or an :exc:`~django.core.exceptions.ImproperlyConfigured` exception, use
+    the explicit setup described below.
 
     When the automatic setup is used, the Debug Toolbar is not compatible with
     :class:`~django.middleware.gzip.GZipMiddleware`. Please disable that
@@ -62,8 +72,8 @@ what it does, or if you prefer defining your settings explicitly, read below.
 Explicit setup
 --------------
 
-First, tell the toolbar not to adjust your settings automatically by adding
-this line in your settings module::
+This is the recommended way to configure the Debug Toolbar. First, disable the
+automatic setup by adding this line in your settings module::
 
     DEBUG_TOOLBAR_PATCH_SETTINGS = False
 
@@ -85,8 +95,9 @@ This example uses the ``__debug__`` prefix, but you can use any prefix that
 doesn't clash with your application's URLs. Note the lack of quotes around
 ``debug_toolbar.urls``.
 
-If the URLs aren't included in your root URLconf, the Debug Toolbar
-automatically appends them.
+.. note::
+
+    The automatic setup appends the Debug Toolbar URLs to the root URLconf.
 
 Middleware
 ~~~~~~~~~~
@@ -105,8 +116,10 @@ Toolbar middleware as early as possible in the list. However, it must come
 after any other middleware that encodes the response's content, such as
 :class:`~django.middleware.gzip.GZipMiddleware`.
 
-If ``MIDDLEWARE_CLASSES`` doesn't contain the middleware, the Debug Toolbar
-automatically adds it the beginning of the list.
+.. note::
+
+    The automatic setup inserts the Debug Toolbar middleware at the beginning
+    of ``MIDDLEWARE_CLASSES``, unless it's already included.
 
 Internal IPs
 ~~~~~~~~~~~~
@@ -116,5 +129,7 @@ setting. (You can change this logic with the ``SHOW_TOOLBAR_CALLBACK``
 option.) For local development, you should add ``'127.0.0.1'`` to
 ``INTERNAL_IPS``.
 
-If ``INTERNAL_IPS`` is empty, the Debug Toolbar automatically sets it to
-``'127.0.0.1'`` and ``'::1'``.
+.. note::
+
+    The automatic setup sets ``INTERNAL_IPS`` to ``'127.0.0.1'`` and
+    ``'::1'``, unless it's already set to a non-empty value.