[1.8.x] Fixed #25156 -- Mentioned django.setup() in the settings overview for standalone Django use.

Backport of 5281f8b635f10b2839dc146d7e44f7d94d1955d8 from master

1 files changed, 23 insertions, 1 deletions

diff --git a/docs/topics/settings.txt b/docs/topics/settings.txt
index bf6a7a75d5..f11001cc8d 100644
--- a/docs/topics/settings.txt
+++ b/docs/topics/settings.txt
@@ -265,7 +265,29 @@ Also, it's an error to call ``configure()`` more than once, or to call
 It boils down to this: Use exactly one of either ``configure()`` or
 ``DJANGO_SETTINGS_MODULE``. Not both, and not neither.
 
-.. _@login_required: ../authentication/#the-login-required-decorator
+Calling ``django.setup()`` is required for "standalone" Django usage
+--------------------------------------------------------------------
+
+If you're using components of Django "standalone" -- for example, writing a
+Python script which loads some Django templates and renders them, or uses the
+ORM to fetch some data -- there's one more step you'll need in addition to
+configuring settings.
+
+After you've either set :envvar:`DJANGO_SETTINGS_MODULE` or called
+``configure()``, you'll need to call :func:`django.setup()` to load your
+settings and populate Django's application registry. For example::
+
+    from django.conf import settings
+    from myapp import myapp_defaults
+
+    settings.configure(default_settings=myapp_defaults, DEBUG=True)
+    django.setup()
+
+    # Now this script can use any part of Django it needs.
+
+Note that calling ``django.setup()`` is only necessary if your code is truly
+standalone. When invoked by your Web server, or through :doc:`django-admin
+</ref/django-admin>`, Django will handle this for you.
 
 .. seealso::