Add :confval:html_js_files

CHANGES

@@ -112,6 +112,7 @@ Features added
   fontsize in code-blocks (refs: #4793)
 * Add :confval:`html_css_files` and :confval:`epub_css_files` for adding CSS
   files from configuration
+* Add :confval:`html_js_files` for adding JS files from configuration
 * #4834: Ensure set object descriptions are reproducible.
 * #4828: Allow to override :confval:`numfig_format` partially.  Full definition
   is not needed.

doc/usage/configuration.rst

@@ -874,6 +874,22 @@ that use Sphinx's HTMLWriter class.
 
    .. versionadded:: 1.8
 
+.. confval:: html_js_files
+
+   A list of JavaScript *filename*.  The entry must be a *filename* string or a
+   tuple containing the *filename* string and the *attributes* dictionary.  The
+   *filename* must be relative to the :confval:`html_static_path`, or a full
+   URI with scheme like ``http://example.org/script.js``.  The *attributes* is
+   used for attributes of ``<script>`` tag.  It defaults to an empty list.
+
+   Example::
+
+       html_js_files = ['script.js',
+                        'https://example.com/scripts/custom.js',
+                        ('custom.js', {'async': 'async'})]
+
+   .. versionadded:: 1.8
+
 .. confval:: html_static_path
 
    A list of paths that contain custom static files (such as style

sphinx/application.py

@@ -13,7 +13,6 @@
 from __future__ import print_function
 
 import os
-import posixpath
 import sys
 import warnings
 from collections import deque
@@ -1030,14 +1029,7 @@ class Sphinx(object):
            Renamed from ``app.add_javascript()``.
            And it allows keyword arguments as attributes of script tag.
         """
-        logger.debug('[app] adding javascript: %r', filename)
-        from sphinx.builders.html import StandaloneHTMLBuilder, JavaScript
-        if '://' in filename:
-            js = JavaScript(filename, **kwargs)  # type: ignore
-        else:
-            js = JavaScript(posixpath.join('_static', filename), **kwargs)
-
-        StandaloneHTMLBuilder.script_files.append(js)
+        self.registry.add_js_file(filename, **kwargs)
 
     def add_css_file(self, filename, **kwargs):
         # type: (unicode, **unicode) -> None

sphinx/builders/html.py

@@ -267,10 +267,6 @@ class StandaloneHTMLBuilder(Builder):
     # use html5 translator by default
     default_html5_translator = False
 
-    # This is a class attribute because it is mutated by Sphinx.add_js_file().
-    script_files = ['_static/jquery.js', '_static/underscore.js',
-                    '_static/doctools.js']  # type: List[unicode]
-
     imgpath = None          # type: unicode
     domain_indices = []     # type: List[Tuple[unicode, Type[Index], List[Tuple[unicode, List[List[Union[unicode, int]]]]], bool]]  # NOQA
 
@@ -284,6 +280,9 @@ class StandaloneHTMLBuilder(Builder):
         # CSS files
         self.css_files = CSSContainer()  # type: List[Dict[unicode, unicode]]
 
+        # JS files
+        self.script_files = []  # type: List[JavaScript]
+
     def init(self):
         # type: () -> None
         self.build_info = self.create_build_info()
@@ -297,6 +296,7 @@ class StandaloneHTMLBuilder(Builder):
         self.init_templates()
         self.init_highlighter()
         self.init_css_files()
+        self.init_js_files()
         if self.config.html_file_suffix is not None:
             self.out_suffix = self.config.html_file_suffix
 
@@ -305,9 +305,6 @@ class StandaloneHTMLBuilder(Builder):
         else:
             self.link_suffix = self.out_suffix
 
-        if self.config.language is not None:
-            if self._get_translations_js():
-                self.script_files.append('_static/translations.js')
         self.use_index = self.get_builder_config('use_index', 'html')
 
         if self.config.html_experimental_html5_writer and not html5_ready:
@@ -374,6 +371,28 @@ class StandaloneHTMLBuilder(Builder):
 
         self.css_files.append(Stylesheet(filename, **kwargs))  # type: ignore
 
+    def init_js_files(self):
+        # type: () -> None
+        self.add_js_file('jquery.js')
+        self.add_js_file('underscore.js')
+        self.add_js_file('doctools.js')
+
+        for filename, attrs in self.app.registry.js_files:
+            self.add_js_file(filename, **attrs)
+
+        for filename, attrs in self.get_builder_config('js_files', 'html'):
+            self.add_js_file(filename, **attrs)
+
+        if self.config.language and self._get_translations_js():
+            self.add_js_file('translations.js')
+
+    def add_js_file(self, filename, **kwargs):
+        # type: (unicode, **unicode) -> None
+        if '://' not in filename:
+            filename = posixpath.join('_static', filename)
+
+        self.script_files.append(JavaScript(filename, **kwargs))  # type: ignore
+
     @property
     def default_translator_class(self):
         # type: () -> nodes.NodeVisitor
@@ -1378,6 +1397,7 @@ class SerializingHTMLBuilder(StandaloneHTMLBuilder):
         self.init_templates()
         self.init_highlighter()
         self.init_css_files()
+        self.init_js_files()
         self.use_index = self.get_builder_config('use_index', 'html')
 
     def get_target_uri(self, docname, typ=None):
@@ -1505,6 +1525,24 @@ def convert_html_css_files(app, config):
     config.html_css_files = html_css_files  # type: ignore
 
 
+def convert_html_js_files(app, config):
+    # type: (Sphinx, Config) -> None
+    """This converts string styled html_js_files to tuple styled one."""
+    html_js_files = []  # type: List[Tuple[unicode, Dict]]
+    for entry in config.html_js_files:
+        if isinstance(entry, string_types):
+            html_js_files.append((entry, {}))
+        else:
+            try:
+                filename, attrs = entry
+                html_js_files.append((filename, attrs))
+            except Exception:
+                logger.warning(__('invalid js_file: %r, ignored'), entry)
+                continue
+
+    config.html_js_files = html_js_files  # type: ignore
+
+
 def setup_js_tag_helper(app, pagename, templatexname, context, doctree):
     # type: (Sphinx, unicode, unicode, Dict, nodes.Node) -> None
     """Set up js_tag() template helper.
@@ -1552,6 +1590,7 @@ def setup(app):
     app.add_config_value('html_logo', None, 'html', string_classes)
     app.add_config_value('html_favicon', None, 'html', string_classes)
     app.add_config_value('html_css_files', [], 'html')
+    app.add_config_value('html_js_files', [], 'html')
     app.add_config_value('html_static_path', [], 'html')
     app.add_config_value('html_extra_path', [], 'html')
     app.add_config_value('html_last_updated_fmt', None, 'html', string_classes)
@@ -1581,6 +1620,7 @@ def setup(app):
 
     # event handlers
     app.connect('config-inited', convert_html_css_files)
+    app.connect('config-inited', convert_html_js_files)
     app.connect('html-page-context', setup_js_tag_helper)
 
     return {

sphinx/registry.py

@@ -91,6 +91,9 @@ class SphinxComponentRegistry(object):
         #: a dict of node class -> tuple of figtype and title_getter function
         self.enumerable_nodes = {}      # type: Dict[nodes.Node, Tuple[unicode, TitleGetter]]
 
+        #: js_files; list of JS paths or URLs
+        self.js_files = []              # type: List[Tuple[unicode, Dict[unicode, unicode]]]
+
         #: LaTeX packages; list of package names and its options
         self.latex_packages = []        # type: List[Tuple[unicode, unicode]]
 
@@ -418,6 +421,11 @@ class SphinxComponentRegistry(object):
     def add_css_files(self, filename, **attributes):
         self.css_files.append((filename, attributes))
 
+    def add_js_file(self, filename, **attributes):
+        # type: (unicode, **unicode) -> None
+        logger.debug('[app] adding js_file: %r, %r', filename, attributes)
+        self.js_files.append((filename, attributes))  # type: ignore
+
     def add_latex_package(self, name, options):
         # type: (unicode, unicode) -> None
         logger.debug('[app] adding latex package: %r', name)

tests/roots/test-html_assets/conf.py

@@ -8,4 +8,6 @@ html_static_path = ['static', 'subdir']
 html_extra_path = ['extra', 'subdir']
 html_css_files = ['css/style.css',
                   ('https://example.com/custom.css', {'title': 'title', 'media': 'print'})]
+html_js_files = ['js/custom.js',
+                 ('https://example.com/script.js', {'async': 'async'})]
 exclude_patterns = ['**/_build', '**/.htpasswd']

tests/test_build_html.py

@@ -1123,6 +1123,11 @@ def test_html_assets(app):
     assert ('<link media="print" rel="stylesheet" title="title" type="text/css" '
             'href="https://example.com/custom.css" />' in content)
 
+    # html_js_files
+    assert '<script type="text/javascript" src="_static/js/custom.js"></script>' in content
+    assert ('<script async="async" type="text/javascript" src="https://example.com/script.js">'
+            '</script>' in content)
+
 
 @pytest.mark.sphinx('html', testroot='basic', confoverrides={'html_copy_source': False})
 def test_html_copy_source(app):