Deprecate builder.script_files (refs: #4439)

CHANGES

@@ -35,6 +35,8 @@ Incompatible changes
   citations
 * #4648: latex: Now "rubric" elements are rendered as unnumbered section title
 * #4983: html: The URL for the productionlist has been changed
+* Modifying a template variable ``script_files`` in templates is allowed now.
+  Please use ``app.add_js_file()`` instead.
 
 Deprecated
 ----------

sphinx/builders/html.py

@@ -93,7 +93,7 @@ def get_stable_hash(obj):
 
 
 class CSSContainer(list):
-    """The container of stylesheets.
+    """The container for stylesheets.
 
     To support the extensions which access the container directly, this wraps
     the entry with Stylesheet class.
@@ -163,6 +163,39 @@ def __new__(cls, filename, *args, **attributes):
         return self
 
 
+class JSContainer(list):
+    """The container for JavaScript scripts."""
+    def insert(self, index, obj):
+        # type: (int, unicode) -> None
+        warnings.warn('builder.script_files is deprecated. '
+                      'Please use app.add_js_file() instead.',
+                      RemovedInSphinx30Warning)
+        super(JSContainer, self).insert(index, obj)
+
+    def extend(self, other):  # type: ignore
+        # type: (List[unicode]) -> None
+        warnings.warn('builder.script_files is deprecated. '
+                      'Please use app.add_js_file() instead.',
+                      RemovedInSphinx30Warning)
+        for item in other:
+            self.append(item)
+
+    def __iadd__(self, other):  # type: ignore
+        # type: (List[unicode]) -> JSContainer
+        warnings.warn('builder.script_files is deprecated. '
+                      'Please use app.add_js_file() instead.',
+                      RemovedInSphinx30Warning)
+        for item in other:
+            self.append(item)
+        return self
+
+    def __add__(self, other):
+        # type: (List[unicode]) -> JSContainer
+        ret = JSContainer(self)
+        ret += other
+        return ret
+
+
 class JavaScript(text_type):
     """A metadata of javascript file.
 
@@ -281,7 +314,7 @@ def __init__(self, app):
         self.css_files = CSSContainer()  # type: List[Dict[unicode, unicode]]
 
         # JS files
-        self.script_files = []  # type: List[JavaScript]
+        self.script_files = JSContainer()  # type: List[JavaScript]
 
     def init(self):
         # type: () -> None

sphinx/themes/basic/search.html

@@ -9,7 +9,10 @@
 #}
 {%- extends "layout.html" %}
 {% set title = _('Search') %}
-{% set script_files = script_files + ['_static/searchtools.js'] %}
+{%- macro script() %}
+    {{ super() }}
+    <script type="text/javascript" src="{{ pathto('_static/searchtools.js', 1) }}"></script>
+{%- endmacro %}
 {% block extrahead %}
   <script type="text/javascript">
     jQuery(function() { Search.loadIndex("{{ pathto('searchindex.js', 1) }}"); });

sphinx/themes/bizstyle/layout.html

@@ -9,7 +9,10 @@
 #}
 {% extends "basic/layout.html" %}
 
-{% set script_files = script_files + ["_static/bizstyle.js"] %}
+{%- macro script() %}
+    {{ super() }}
+    <script type="text/javascript" src="{{ pathto('_static/bizstyle.js', 1) }}"></script>
+{%- endmacro %}
 
 {# put the sidebar before the body #}
 {% block sidebar1 %}{{ sidebar() }}{% endblock %}

sphinx/themes/classic/layout.html

@@ -10,5 +10,8 @@
 {%- extends "basic/layout.html" %}
 
 {% if theme_collapsiblesidebar|tobool %}
-{% set script_files = script_files + ['_static/sidebar.js'] %}
+{%- macro script() %}
+    {{ super() }}
+    <script type="text/javascript" src="{{ pathto('_static/sidebar.js', 1) }}"></script>
+{%- endmacro %}
 {% endif %}

sphinx/themes/scrolls/layout.html

@@ -9,11 +9,14 @@
     :license: BSD, see LICENSE for details.
 #}
 {%- extends "basic/layout.html" %}
-{% set script_files = script_files + ['_static/theme_extras.js'] %}
 {%- block css %}
-  {{ super() }}
+    {{ super() }}
     <link rel="stylesheet" href="_static/print.css" type="text/css" />
 {%- endblock %}
+{%- macro script() %}
+    {{ super() }}
+    <script type="text/javascript" src="{{ pathto('_static/theme_extras.js', 1) }}"></script>
+{%- endmacro %}
 {# do not display relbars #}
 {% block relbar1 %}{% endblock %}
 {% block relbar2 %}{% endblock %}