Rename app.add_javascript() to add_js_file()

CHANGES

@@ -53,6 +53,7 @@ Deprecated
 * ``env._nitpick_ignore`` is deprecated
 * ``app.override_domain()`` is deprecated
 * ``app.add_stylesheet()`` is deprecated
+* ``app.add_javascript()`` is deprecated
 * ``sphinx.versioning.prepare()`` is deprecated
 * ``Config.__init__()`` has changed;  the *dirname*, *filename* and *tags*
   argument has been deprecated

doc/extdev/appapi.rst

@@ -71,7 +71,7 @@ package.
 
 .. automethod:: Sphinx.add_post_transform(transform)
 
-.. automethod:: Sphinx.add_javascript(filename, **kwargs)
+.. automethod:: Sphinx.add_js_file(filename, **kwargs)
 
 .. automethod:: Sphinx.add_stylesheet(filename, alternate=None, title=None)
 

doc/extdev/index.rst

@@ -126,6 +126,11 @@ The following is a list of deprecated interface.
      - 4.0
      - :meth:`~sphinx.application.Sphinx.add_css_file()`
 
+   * - :meth:`~sphinx.application.Sphinx.add_javascript()`
+     - 1.8
+     - 4.0
+     - :meth:`~sphinx.application.Sphinx.add_js_file()`
+
    * - ``sphinx.ext.mathbase.MathDomain``
      - 1.8
      - 3.0

sphinx/application.py

@@ -999,6 +999,14 @@ def add_post_transform(self, transform):
         self.registry.add_post_transform(transform)
 
     def add_javascript(self, filename, **kwargs):
+        # type: (unicode, **unicode) -> None
+        """An alias of :meth:`add_js_file`."""
+        warnings.warn('The app.add_javascript() is deprecated. '
+                      'Please use app.add_js_file() instead.',
+                      RemovedInSphinx40Warning)
+        self.add_js_file(filename, **kwargs)
+
+    def add_js_file(self, filename, **kwargs):
         # type: (unicode, **unicode) -> None
         """Register a JavaScript file to include in the HTML output.
 
@@ -1009,16 +1017,17 @@ def add_javascript(self, filename, **kwargs):
 
         Example::
 
-            app.add_javascript('example.js')
+            app.add_js_file('example.js')
             # => <scrtipt src="_static/example.js"></script>
 
-            app.add_javascript('example.js', async="async")
+            app.add_js_file('example.js', async="async")
             # => <scrtipt src="_static/example.js" async="async"></script>
 
         .. versionadded:: 0.5
 
         .. versionchanged:: 1.8
-           Allows keyword arguments as attributes of script tag.
+           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

sphinx/builders/html.py

@@ -266,7 +266,7 @@ class StandaloneHTMLBuilder(Builder):
     # use html5 translator by default
     default_html5_translator = False
 
-    # This is a class attribute because it is mutated by Sphinx.add_javascript.
+    # 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]
 

sphinx/ext/jsmath.py

@@ -64,7 +64,7 @@ def builder_inited(app):
     if not app.config.jsmath_path:
         raise ExtensionError('jsmath_path config value must be set for the '
                              'jsmath extension to work')
-    app.add_javascript(app.config.jsmath_path)
+    app.add_js_file(app.config.jsmath_path)
 
 
 def setup(app):

sphinx/ext/mathjax.py

@@ -72,7 +72,7 @@ def builder_inited(app):
     if not app.config.mathjax_path:
         raise ExtensionError('mathjax_path config value must be set for the '
                              'mathjax extension to work')
-    app.add_javascript(app.config.mathjax_path)
+    app.add_js_file(app.config.mathjax_path)
 
 
 def setup(app):

tests/roots/test-root/conf.py

@@ -105,6 +105,6 @@ def setup(app):
     app.add_directive('clsdir', ClassDirective)
     app.add_object_type('userdesc', 'userdescrole', '%s (userdesc)',
                         userdesc_parse, objname='user desc')
-    app.add_javascript('file://moo.js')
+    app.add_js_file('file://moo.js')
     app.add_source_suffix('.foo', 'foo')
     app.add_source_parser(parsermod.Parser)