Drop JavaScript Frameworks (#10028)

* Delete jQuery and underscore.js

* Move underscores.js setup to searchtools.js

* Update jQuery.url(en|de)code

* Update jQuery.getQueryParameters

* Firefox bug is no longer present

xref https://bugzilla.mozilla.org/show_bug.cgi?id=645075#c49

* Update jQuery.fn.highlightText

* Use enum instead of magic number

* Update test descriptions to remove obsolete jQuery reference

* Update Documentation.getCurrentURL

* Revert accidental fix of Documentation.getCurrentURL

* Update Documentation.initOnKeyListeners

* Update Documentation.hideSearchWords

* Update Documentation.highlightSearchWords

* Update Documentation.initDomainIndexTable

* Use arrow functions and const

* Replace $(document).ready

* Strict mode

* Move Documentation.hideSearchWords next to Documentation.highlightSearchWords

* Update translation functions in Documentation

* Replace $(document).ready in searchtools.js

* Update Scorer

* Update Search.hasIndex, Search.deferQuery, Search.stopPulse

* Prefer window.location

* Update Search.init

* Update Search.loadIndex

* Update Search.setIndex

* Update Search.startPulse

* Add _escapeRegExp

* Update Search.makeSearchSummary

* Update Search.htmlToText

* Update Search.performSearch

* Factor out _displayNextItem

* Update Search.query

* Update Search.performObjectSearch

* Update Search.performTermsSearch

* Remove underscores.js setup

* Use Sets

* Update test configuration

* Fix test failures

* Drop unused make/get URL functions

* Strict mode in searchtools.js

* Remove outmoded check for jQuery and underscore.js

* Ran prettier

prettier --print-width 120 --no-semi --quote-props as-needed --no-bracket-spacing --arrow-parens avoid --write sphinx/themes/basic/static

* Remove more references to jQuery and underscore.js

* Remove jQuery and underscore.js licences

* Update classic theme for no jQuery

* Update all other themes for no jQuery

* Restore jQuery & underscores.js to Sphinx themes

Enables a more gradual deprecation

* Added deprecation note to CHANGES

* Run prettier with defaults

* Update deprecation message to include extensions, note that sources must be copied

* oops

* Address Pradyun's feedback

* Forgot this one

* `let` doesn't work, as it is scoped to the block...

* Remove missed jQuery in sphinx13 theme

.github/workflows/nodejs.yml

@@ -6,14 +6,15 @@ jobs:
   build:
     runs-on: ubuntu-latest
     env:
-      node-version: 10.7
+      node-version: 16
 
     steps:
     - uses: actions/checkout@v2
     - name: Use Node.js ${{ env.node-version }}
-      uses: actions/setup-node@v1
+      uses: actions/setup-node@v2
       with:
         node-version: ${{ env.node-version }}
+        cache: "npm"
     - run: npm install
     - name: Run headless test
       uses: GabrielBB/xvfb-action@v1

AUTHORS

@@ -18,6 +18,7 @@ Other co-maintainers:
 
 Other contributors, listed alphabetically, are:
 
+* Adam Turner -- JavaScript improvements
 * Alastair Houghton -- Apple Help builder
 * Alexander Todorov -- inheritance_diagram tests and improvements
 * Andi Albrecht -- agogo theme

CHANGES

@@ -27,6 +27,23 @@ Incompatible changes
 Deprecated
 ----------
 
+* #10028: jQuery and underscore.js will no longer be automatically injected into
+  themes from Sphinx 6.0. If you develop a theme or extension that uses the
+  ``jQuery``, ``$``, or ``$u`` global objects, you need to update your
+  JavaScript or use the mitigation below.
+
+  To re-add jQuery and underscore.js, you will need to copy ``jquery.js`` and
+  ``underscore.js`` from `the Sphinx repository`_ to your ``static`` directory,
+  and add the following to your ``layout.html``:
+
+  .. _the Sphinx repository: https://github.com/sphinx-doc/sphinx/tree/v4.3.2/sphinx/themes/basic/static
+  .. code-block:: html+jinja
+
+     {%- block scripts %}
+         <script src="{{ pathto('_static/jquery.js', resource=True) }}"></script>
+         <script src="{{ pathto('_static/underscore.js', resource=True) }}"></script>
+         {{ super() }}
+     {%- endblock %}
 * setuptools integration.  The ``build_sphinx`` sub-command for setup.py is
   marked as deprecated to follow the policy of setuptools team.
 * The ``locale`` argument of ``sphinx.util.i18n:babel_format_date()`` becomes
@@ -41,6 +58,9 @@ Features added
 * #9075: autodoc: The default value of :confval:`autodoc_typehints_format` is
   changed to ``'smart'``.  It will suppress the leading module names of
   typehints (ex. ``io.StringIO`` -> ``StringIO``).
+* #10028: Removed internal usages of JavaScript frameworks (jQuery and
+  underscore.js) and modernised ``doctools.js`` and ``searchtools.js`` to
+  EMCAScript 2018.
 
 Bugs fixed
 ----------

doc/_templates/indexsidebar.html

@@ -14,7 +14,7 @@ <h3>{%trans%}Questions? Suggestions?{%endtrans%}</h3>
 <form action="https://groups.google.com/group/sphinx-users/boxsubscribe"
       class="subscribeform">
   <input type="text" name="email" value="your@email"
-         onfocus="$(this).val('');" />
+         onfocus="this.value = ''" />
   <input type="submit" name="sub" value="Subscribe" />
 </form>
 </div>

doc/_themes/sphinx13/layout.html

@@ -27,31 +27,28 @@
     </style>
     <script>
       // intelligent scrolling of the sidebar content
-      $(window).scroll(function() {
-        var sb = $('.sphinxsidebarwrapper');
-        var win = $(window);
-        var sbh = sb.height();
-        var offset = $('.sphinxsidebar').position()['top'];
-        var wintop = win.scrollTop();
-        var winbot = wintop + win.innerHeight();
-        var curtop = sb.position()['top'];
-        var curbot = curtop + sbh;
+      window.onscroll = () => {
+        const sb = document.getElementsByClassName('sphinxsidebarwrapper')[0]
+        const sbh = sb.offsetHeight
+        const offset = document.getElementsByClassName('sphinxsidebar')[0].offsetTop;
+        const wintop = window.scrollTop;
+        const winbot = wintop + window.offsetHeight
+        const curtop = sb.offsetTop;
+        const curbot = curtop + sbh;
         // does sidebar fit in window?
-        if (sbh < win.innerHeight()) {
+        if (sbh < window.offsetHeight) {
           // yes: easy case -- always keep at the top
-          sb.css('top', $u.min([$u.max([0, wintop - offset - 10]),
-                                $(document).height() - sbh - 200]));
+          sb.style.top = Math.min(Math.max(0, wintop - offset - 10), window.innerHeight - sbh - 200)
         } else {
           // no: only scroll if top/bottom edge of sidebar is at
           // top/bottom edge of window
           if (curtop > wintop && curbot > winbot) {
-            sb.css('top', $u.max([wintop - offset - 10, 0]));
+              sb.style.top = Math.max(wintop - offset - 10, 0)
           } else if (curtop < wintop && curbot < winbot) {
-            sb.css('top', $u.min([winbot - sbh - offset - 20,
-                                  $(document).height() - sbh - 200]));
+              sb.style.top = Math.min(winbot - sbh - offset - 20, window.innerHeight - sbh - 200)
           }
         }
-      });
+      }
     </script>
 {%- endif %}
 {% endblock %}

karma.conf.js

@@ -15,8 +15,6 @@ module.exports = function(config) {
 
     // list of files / patterns to load in the browser
     files: [
-      'sphinx/themes/basic/static/underscore.js',
-      'sphinx/themes/basic/static/jquery.js',
       'sphinx/themes/basic/static/doctools.js',
       'sphinx/themes/basic/static/searchtools.js',
       'tests/js/*.js'
@@ -59,7 +57,7 @@ module.exports = function(config) {
 
     // start these browsers
     // available browser launchers: https://npmjs.org/browse/keyword/karma-launcher
-    browsers: ['Chrome', 'Firefox'],
+    browsers: ["Firefox"],
 
 
     // Continuous Integration mode