Merge pull request #4178 from tk0miya/deprecate_string_for_html_sidebars

a single string value for ``html_sidebars`` will be deprecated in 2.0

Author: tk0miya

CHANGES

@@ -15,6 +15,9 @@ Incompatible changes
 Deprecated
 ----------
 
+* using a string value for :confval:`html_sidebars` is deprecated and only list
+  values will be accepted at 2.0.
+
 Features added
 --------------
 

doc/config.rst

@@ -829,6 +829,10 @@ that use Sphinx's HTMLWriter class.
      between the ``'sourcelink.html'`` and ``'searchbox.html'`` entries.  This
      is for compatibility with Sphinx versions before 1.0.
 
+   .. deprecated:: 1.7
+
+      a single string value for ``html_sidebars`` will be removed in 2.0
+
    Builtin sidebar templates that can be rendered are:
 
    * **localtoc.html** -- a fine-grained table of contents of the current

sphinx/builders/html.py

@@ -901,6 +901,11 @@ def has_wildcard(pattern):
             # 0.x compatible mode: insert custom sidebar before searchbox
             customsidebar = sidebars
             sidebars = None
+            warnings.warn('Now html_sidebars only allows list of sidebar '
+                          'templates as a value. Support for a string value '
+                          'will be removed at Sphinx-2.0.',
+                          RemovedInSphinx20Warning)
+
         ctx['sidebars'] = sidebars
         ctx['customsidebar'] = customsidebar