Fixes #4452 - Clearer Django settings documentation (#4467)

* reword django settings section in first steps

* anchor link for django admonition

* mention django-specific settings config

docs/django/first-steps-with-django.rst

@@ -84,18 +84,20 @@ for Celery. This means that you don't have to use multiple
 configuration files, and instead configure Celery directly
 from the Django settings; but you can also separate them if wanted.
 
+.. code-block:: python
+
+    app.config_from_object('django.conf:settings', namespace='CELERY')
+
 The uppercase name-space means that all Celery configuration options
 must be specified in uppercase instead of lowercase, and start with
 ``CELERY_``, so for example the :setting:`task_always_eager` setting
 becomes ``CELERY_TASK_ALWAYS_EAGER``, and the :setting:`broker_url`
 setting becomes ``CELERY_BROKER_URL``.
 
-You can pass the object directly here, but using a string is better since
-then the worker doesn't have to serialize the object.
-
-.. code-block:: python
-
-    app.config_from_object('django.conf:settings', namespace='CELERY')
+You can pass the settings object directly instead, but using a string
+is better since then the worker doesn't have to serialize the object.
+The ``CELERY_`` namespace is also optional, but recommended (to
+prevent overlap with other Django settings).
 
 Next, a common practice for reusable apps is to define all tasks
 in a separate ``tasks.py`` module, and Celery does have a way to

docs/userguide/configuration.rst

@@ -47,8 +47,13 @@ names, are the renaming of some prefixes, like ``celerybeat_`` to ``beat_``,
 ``celeryd_`` to ``worker_``, and most of the top level ``celery_`` settings
 have been moved into a new  ``task_`` prefix.
 
-Celery will still be able to read old configuration files, so there's no
-rush in moving to the new settings format.
+.. note::
+
+    Celery will still be able to read old configuration files, so
+    there's no rush in moving to the new settings format. Furthermore,
+    we provide the ``celery upgrade`` command that should handle plenty
+    of cases (including :ref:`Django <latentcall-django-admonition>`).
+
 
 =====================================  ==============================================
 **Setting name**                       **Replace with**

docs/whatsnew-4.0.rst

@@ -387,6 +387,7 @@ This command will modify your module in-place to use the new lower-case
 names (if you want uppercase with a "``CELERY``" prefix see block below),
 and save a backup in :file:`proj/settings.py.orig`.
 
+.. _latentcall-django-admonition:
 .. admonition:: For Django users and others who want to keep uppercase names
 
     If you're loading Celery configuration from the Django settings module