Merge pull request #4777 from divio/documentation-general

Improved installation notes for Django 1.8
django-cms · Nov 27, 2015 · 04344af · 04344af
2 parents 5df7a42 + fad5454
commit 04344af
Show file tree

Hide file tree

Showing 3 changed files with 51 additions and 50 deletions.
diff --git a/docs/how_to/install.rst b/docs/how_to/install.rst
@@ -412,23 +412,29 @@ Notice that django CMS v3.2 introduces a new middleware:
 ``cms.middleware.utils.ApphookReloadMiddleware``. This should be placed very
 near the top of your middleware classes tuple/list.
 
-You need at least the following :setting:`django:TEMPLATE_CONTEXT_PROCESSORS`::
-
-    TEMPLATE_CONTEXT_PROCESSORS = (
-        'django.contrib.auth.context_processors.auth',
-        'django.contrib.messages.context_processors.messages',
-        'django.core.context_processors.i18n',
-        'django.core.context_processors.request',
-        'django.core.context_processors.media',
-        'django.core.context_processors.static',
-        'sekizai.context_processors.sekizai',
-        'cms.context_processors.cms_settings',
-    )
-
 .. note::
 
-    This setting will be missing from automatically generated Django settings
-    files, so you will have to add it.
+    In Django 1.8, the ``TEMPLATE_DIRS``, ``TEMPLATE_LOADERS`` and ``TEMPLATE_CONTEXT_PROCESSORS``
+    settings are rolled into the ``TEMPLATES`` setting.
+
+    For earlier versions, put the ``context_processors`` and items listed into
+    ``TEMPLATE_CONTEXT_PROCESSORS``, the ``DIRS`` items into ``TEMPLATE_DIRS`` and so on.
+
+.. code-block:: python
+   :emphasize-lines: 7,8
+
+    TEMPLATES = [
+        {
+            'DIRS': [os.path.join(BASE_DIR, "templates"),],
+            'OPTIONS': {
+                'context_processors': [
+                    # ...
+                    'sekizai.context_processors.sekizai',
+                    'cms.context_processors.cms_settings',
+                    ],
+                },
+            },
+        ]
 
 .. warning::
 
@@ -450,7 +456,7 @@ You need at least the following :setting:`django:TEMPLATE_CONTEXT_PROCESSORS`::
 
         * ``INSTALLED_APPS``: must contain ``'django.contrib.messages'``
         * ``MIDDLEWARE_CLASSES``: must contain ``'django.contrib.messages.middleware.MessageMiddleware'``
-        * ``TEMPLATE_CONTEXT_PROCESSORS``: must contain ``'django.contrib.messages.context_processors.messages'``
+        * ``TEMPLATES["OPTIONS"]["context_processors"]``: must contain ``'django.contrib.messages.context_processors.messages'``
 
 
 Point your :setting:`django:STATIC_ROOT` to where the static files should live
@@ -470,14 +476,6 @@ setting::
     Please make sure both the ``static`` and ``media`` sub-folders exist in your
     project and are writeable.
 
-Now add a little magic to the :setting:`django:TEMPLATE_DIRS` section of the file::
-
-    TEMPLATE_DIRS = (
-        # The docs say it should be absolute path: BASE_DIR is precisely one.
-        # Life is wonderful!
-        os.path.join(BASE_DIR, "templates"),
-    )
-
 Add at least one template to :setting:`CMS_TEMPLATES`; for example::
 
     CMS_TEMPLATES = (

diff --git a/docs/introduction/install.rst b/docs/introduction/install.rst
@@ -54,7 +54,7 @@ Run it to create a new Django project called ``mysite``::
 This means:
 
 * run the django CMS installer
-* install Django Filer too (``-f``)
+* install Django Filer too (``-f``) - **required for this tutorial**
 * use the current directory as the parent of the new project directory (``-p .``)
 * call the new project directory ``mysite``
 

diff --git a/docs/introduction/third_party.rst b/docs/introduction/third_party.rst
@@ -26,7 +26,7 @@ Django settings
 
 Add the application and any of its requirements that are not there already to
 ``INSTALLED_APPS`` in ``settings.py``. Some *will* be already present; it's up
-to you to check them:
+to you to check them because you need to avoid duplication:
 
 .. code-block:: python
 
@@ -57,11 +57,12 @@ sophisticated image cropping. For this to work it needs its own thumbnail proces
 ``settings.py`` in place of ``easy_thumbnails.processors.scale_and_crop``:
 
 .. code-block:: python
+   :emphasize-lines: 4,5
 
     THUMBNAIL_PROCESSORS = (
         'easy_thumbnails.processors.colorspace',
         'easy_thumbnails.processors.autocrop',
-        # 'easy_thumbnails.processors.scale_and_crop',
+        # 'easy_thumbnails.processors.scale_and_crop',  # disable this one
         'filer.thumbnail_processors.scale_and_crop_with_subject_location',
         'easy_thumbnails.processors.filters',
     )
@@ -82,13 +83,14 @@ for different CSS frameworks. We're using the Bootstrap 3 in this tutorial, so l
 ``STATICFILES_FINDERS``
 =======================
 
-Add the boilerplates static files finder to ``STATICFILES_FINDERS``:
+Add the boilerplates static files finder to ``STATICFILES_FINDERS``, *immediately before*
+``django.contrib.staticfiles.finders.AppDirectoriesFinder``:
 
 .. code-block:: python
+   :emphasize-lines: 3
 
     STATICFILES_FINDERS = [
         'django.contrib.staticfiles.finders.FileSystemFinder',
-        # important! place right before django.contrib.staticfiles.finders.AppDirectoriesFinder
         'aldryn_boilerplates.staticfile_finders.AppDirectoriesFinder',
         'django.contrib.staticfiles.finders.AppDirectoriesFinder',
     ]
@@ -97,32 +99,33 @@ If ``STATICFILES_FINDERS`` is not defined in your ``settings.py`` just copy and
 above.
 
 
-``TEMPLATE_LOADERS``
-====================
+``TEMPLATES``
+=============
 
-Add the boilerplate template loader to ``TEMPLATE_LOADERS``:
-
-.. code-block:: python
-
-    TEMPLATE_LOADERS = (
-        'django.template.loaders.filesystem.Loader',
-        'aldryn_boilerplates.template_loaders.AppDirectoriesLoader',
-        'django.template.loaders.app_directories.Loader',
-        'django.template.loaders.eggs.Loader'
-    )
+.. important::
 
+    In Django 1.8, the ``TEMPLATE_LOADERS`` and ``TEMPLATE_CONTEXT_PROCESSORS`` settings are
+    rolled into the ``TEMPLATES`` setting. We're assuming you're using Django 1.8 here.
 
-``TEMPLATE_CONTEXT_PROCESSORS``
-===============================
-
-Add the boilerplates context processor to ``TEMPLATE_CONTEXT_PROCESSORS``:
 
 .. code-block:: python
-
-    TEMPLATE_CONTEXT_PROCESSORS = [
-        # ...
-        'aldryn_boilerplates.context_processors.boilerplate',
-    ]
+   :emphasize-lines: 7,11
+
+    TEMPLATES = [
+        {
+            # ...
+            'OPTIONS': {
+                'context_processors': [
+                    # ...
+                    'aldryn_boilerplates.context_processors.boilerplate',
+                    ],
+                'loaders': [
+                    # ...
+                    'aldryn_boilerplates.template_loaders.AppDirectoriesLoader',
+                    ],
+                },
+            },
+        ]
 
 
 ********************