Merge "Remove and deprecate dashboards config from settings file"

doc/source/topics/settings.rst

@@ -42,24 +42,41 @@ behavior of your Horizon installation. All of them are contained in the
 ``dashboards``
 --------------
 
+.. warning::
+
+   In OpenStack Dashboard configuration, we suggest **NOT** to use this
+   setting. Please specify the order of dashboard using the
+   :ref:`pluggable-settings-label`.
+
+   Both the pluggable dashboard mechanism (OpenStack Dashboard default) and
+   this setting ``dashboard`` configure the order of dashboards and
+   the setting ``dashboard`` precedes the pluggable dashboard mechanism.
+   Specifying the order in two places may cause confusion.
+   Please use this parameter only when the pluggable config is not used.
+
 .. versionadded:: 2012.1(Essex)
 
 Default: ``None``
 
 Horizon Dashboards are automatically discovered in the following way:
 
+* By adding a configuration file to the ``openstack_dashboard/local/enabled``
+  directory (for more information see :ref:`pluggable-settings-label`).
+  This is the default way in OpenStack Dashboard.
 * By traversing Django's list of
   `INSTALLED_APPS <https://docs.djangoproject.com/en/1.4/ref/settings/#std:setting-INSTALLED_APPS>`_
   and importing any files that have the name ``"dashboard.py"`` and include
   code to register themselves as a Horizon dashboard.
-* By adding a configuration file to the ``openstack_dashboard/local/enabled``
-  directory (for more information see :ref:`pluggable-settings-label`).
 
-By default, these dashboards are ordered alphabetically.
-However, if a list of dashboard slugs is provided in this setting, the supplied
+By default, dashboards defined by ``openstack_dashboard/local/enabled`` are
+displayed first in the alphabetical order of the config files, and then the
+remaining dashboards discovered by traversing INSTALLED_APPS are displayed
+in the alphabetical order.
+
+If a list of ``dashboard`` slugs is provided in this setting, the supplied
 ordering is applied to the list of discovered dashboards. If the list of
 dashboard slugs is shorter than the number of discovered dashboards, the
-remaining dashboards are appended in alphabetical order.
+remaining dashboards are appended in the default order described above.
 
 The dashboards listed must be in a Python module which
 is included in the ``INSTALLED_APPS`` list and on the Python path.
@@ -67,6 +84,19 @@ is included in the ``INSTALLED_APPS`` list and on the Python path.
 ``default_dashboard``
 ---------------------
 
+.. warning::
+
+   In OpenStack Dashboard configuration, we suggest **NOT** to use this
+   setting. Please specify the order of dashboard using the
+   :ref:`pluggable-settings-label`.
+
+   The default dashboard can be configured via both the pluggable
+   dashboard mechanism (OpenStack Dashboard default) and this setting
+   ``default_dashboard``, and if both are specified, the setting
+   by the pluggable dashboard mechanism will be used.
+   Specifying the default dashboard in two places may cause confusion.
+   Please use this parameter only when the pluggable config is not used.
+
 .. versionadded:: 2012.1(Essex)
 
 Default: ``None``

openstack_dashboard/local/local_settings.py.example

@@ -52,8 +52,6 @@ TEMPLATE_DEBUG = DEBUG
 
 # Default OpenStack Dashboard configuration.
 HORIZON_CONFIG = {
-    'dashboards': ('project', 'admin', 'settings',),
-    'default_dashboard': 'project',
     'user_home': 'openstack_dashboard.views.get_user_home',
     'ajax_queue_limit': 10,
     'auto_fade_alerts': {

openstack_dashboard/settings.py

@@ -73,8 +73,6 @@ STATIC_URL = '/static/'
 ROOT_URLCONF = 'openstack_dashboard.urls'
 
 HORIZON_CONFIG = {
-    'dashboards': ('project', 'admin', 'router',),
-    'default_dashboard': 'project',
     'user_home': 'openstack_dashboard.views.get_user_home',
     'ajax_queue_limit': 10,
     'auto_fade_alerts': {

openstack_dashboard/test/test_plugins/panel_group_tests.py

@@ -28,6 +28,11 @@ PANEL_GROUP_SLUG = 'plugin_panel_group'
 HORIZON_CONFIG = copy.deepcopy(settings.HORIZON_CONFIG)
 INSTALLED_APPS = list(settings.INSTALLED_APPS)
 
+# NOTE: Ensure dashboards and default_dashboard are not included in
+# HORIZON_CONFIG to ensure warning messages from update_dashboards below.
+HORIZON_CONFIG.pop('dashboards', None)
+HORIZON_CONFIG.pop('default_dashboard', None)
+
 util_settings.update_dashboards([
     openstack_dashboard.test.test_plugins.panel_group_config,
 ], HORIZON_CONFIG, INSTALLED_APPS)

openstack_dashboard/test/test_plugins/panel_tests.py

@@ -28,6 +28,11 @@ from openstack_dashboard.utils import settings as util_settings
 HORIZON_CONFIG = copy.deepcopy(settings.HORIZON_CONFIG)
 INSTALLED_APPS = list(settings.INSTALLED_APPS)
 
+# NOTE: Ensure dashboards and default_dashboard are not included in
+# HORIZON_CONFIG to ensure warning messages from update_dashboards below.
+HORIZON_CONFIG.pop('dashboards', None)
+HORIZON_CONFIG.pop('default_dashboard', None)
+
 util_settings.update_dashboards([
     openstack_dashboard.test.test_plugins.panel_config,
 ], HORIZON_CONFIG, INSTALLED_APPS)

openstack_dashboard/utils/settings.py

@@ -12,6 +12,7 @@
 
 import collections
 import logging
+import os
 import pkgutil
 
 from django.utils import importlib
@@ -84,6 +85,17 @@ def update_dashboards(modules, horizon_config, installed_apps):
     deferred until the horizon autodiscover is completed, configurations are
     applied in alphabetical order of files where it was imported.
     """
+    config_dashboards = horizon_config.get('dashboards', [])
+    if config_dashboards or horizon_config.get('default_dashboard'):
+        logging.warning(
+            '"dashboards" and "default_dashboard" in (local_)settings is '
+            'DEPRECATED now and may be unsupported in some future release. '
+            'The preferred way to specify the order of dashboards and the '
+            'default dashboard is the pluggable dashboard mechanism (in %s).',
+            ', '.join([os.path.abspath(module.__path__[0])
+                       for module in modules])
+        )
+
     enabled_dashboards = []
     disabled_dashboards = []
     exceptions = {}
@@ -112,7 +124,6 @@ def update_dashboards(modules, horizon_config, installed_apps):
             config.pop("__builtins__", None)
             panel_customization.append(config)
     # Preserve the dashboard order specified in settings
-    config_dashboards = horizon_config.get('dashboards', [])
     dashboards = ([d for d in config_dashboards
                    if d not in disabled_dashboards] +
                   [d for d in enabled_dashboards