Provide a solution to prevent monkey-patching the settings.

This is necessary to work around extreme cases of circular imports.
We really need to reverse URLs at import time and this isn't always
possible.

2 files changed, 19 insertions, 0 deletions

diff --git a/docs/configuration.rst b/docs/configuration.rst
index 1e527e2..b0a67b1 100644
--- a/docs/configuration.rst
+++ b/docs/configuration.rst
@@ -12,6 +12,13 @@ settings module to customize its behavior.
     it'll prevent you from taking advantage of better defaults that may be
     introduced in future releases.
 
+DEBUG_TOOLBAR_PATCH_SETTINGS
+----------------------------
+
+This setting defines whether the toolbar will attempt to automatically adjust
+your project's settings, as described in the :doc:`installation instructions
+<installation>`. By default it has the same value as your ``DEBUG`` setting.
+
 DEBUG_TOOLBAR_PANELS
 --------------------
 
diff --git a/docs/installation.rst b/docs/installation.rst
index 221d85f..921cfe8 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -51,9 +51,21 @@ what it does, or if you prefer defining your settings explicitly, read below.
     during the start-up sequence. This works with ``manage.py runserver``
     because it validates models before serving requests.
 
+.. warning::
+
+    The automatic setup imports your project's URLconf in order to add the
+    Debug Toolbar's URLs. This may trigger circular imports when the URLconf
+    imports views that import models. If you're hitting an :exc:`ImportError`,
+    follow the explicit setup instructions.
+
 Explicit setup
 --------------
 
+First, tell the toolbar not to adjust your settings automatically by adding
+this line in your settings module::
+
+    DEBUG_TOOLBAR_PATCH_SETTINGS = False
+
 URLconf
 ~~~~~~~