Add configuration option jquery_use_sri and bump to 4.0.0

CHANGES.rst

@@ -1,3 +1,12 @@
+Release 4.0.0 (24/01/2023)
+==========================
+
+* Enforcing SRI check broke documentation builds displayed directly from local filesystem (``file:///``).
+  Make SRI checks optional with setting ``jquery_sri_enable``, default is ``False``.
+  See `sphinx_rtd_theme#1420`_.
+
+.. _sphinx_rtd_theme#1420: https://github.com/readthedocs/sphinx_rtd_theme/issues/1420
+
 Release 3.0.0 (03/11/2022)
 ==========================
 

README.rst

@@ -19,3 +19,15 @@ To use it, add ``sphinxcontrib.jquery`` as a Sphinx extension:
        "sphinxcontrib.jquery",
    ]
    ...
+
+Configuration
+-------------
+
+```
+# Enable Subresource Integrity (SRI) such that
+# <script ... integrity="<hash>"> are included on JS files
+# See more: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
+# Default: False
+
+jquery_sri_enable = True
+```

sphinxcontrib/jquery/__init__.py

@@ -3,8 +3,8 @@
 
 import sphinx
 
-__version__ = "3.0.0"
-version_info = (3, 0, 0)
+__version__ = "4.0.0"
+version_info = (4, 0, 0)
 
 _ROOT_DIR = path.abspath(path.dirname(__file__))
 _FILES = (
@@ -19,18 +19,32 @@
 )
 
 
-def setup(app):
+def add_js_files(app, config):
     jquery_installed = getattr(app, "_sphinxcontrib_jquery_installed", False)
+
     if sphinx.version_info[:2] >= (6, 0) and not jquery_installed:
         makedirs(path.join(app.outdir, '_static'), exist_ok=True)
         for (filename, integrity) in _FILES:
-            app.add_js_file(filename, integrity=integrity, priority=100)
+            # The default is not not enable SRI because it does not trigger the hash
+            # check but instead blocks the request when viewing documentation locally
+            # through the file:// "protocol".
+            if config.jquery_sri_enable:
+                app.add_js_file(filename, integrity=integrity, priority=100)
+            else:
+                app.add_js_file(filename, priority=100)
             shutil.copyfile(
                 path.join(_ROOT_DIR, filename),
                 path.join(app.outdir, '_static', filename)
             )
         app._sphinxcontrib_jquery_installed = True
 
+
+def setup(app):
+    # Configuration value for enabling SRI checks
+    app.add_config_value("jquery_sri_enable", default=False, rebuild="html", types=[bool])
+
+    app.connect('config-inited', add_js_files)
+
     return {
         "parallel_read_safe": True,
         "parallel_write_safe": True,

tests/test_jquery_installed.py

@@ -32,7 +32,7 @@ def inner(**kwargs):
 @pytest.mark.skipif(sphinx.version_info[:2] < (6, 0),
                     reason="Requires Sphinx 6.0 or greater")
 def test_jquery_installed_sphinx_ge_60(blank_app):
-    out_dir = blank_app(confoverrides={"extensions": ["sphinxcontrib.jquery"]})
+    out_dir = blank_app(confoverrides={"extensions": ["sphinxcontrib.jquery"], "jquery_sri_enable": True})
 
     text = out_dir.joinpath("index.html").read_text(encoding="utf-8")
     assert ('<script '
@@ -47,6 +47,22 @@ def test_jquery_installed_sphinx_ge_60(blank_app):
     assert static_dir.joinpath('_sphinx_javascript_frameworks_compat.js').is_file()
 
 
+@pytest.mark.skipif(sphinx.version_info[:2] < (6, 0),
+                    reason="Requires Sphinx 6.0 or greater")
+def test_jquery_installed_sphinx_ge_60(blank_app):
+    out_dir = blank_app(confoverrides={"extensions": ["sphinxcontrib.jquery"]})
+
+    text = out_dir.joinpath("index.html").read_text(encoding="utf-8")
+    assert ('<script '
+            'src="_static/jquery.js"></script>') in text
+    assert ('<script '
+            'src="_static/_sphinx_javascript_frameworks_compat.js"></script>') in text
+
+    static_dir = out_dir / '_static'
+    assert static_dir.joinpath('jquery.js').is_file()
+    assert static_dir.joinpath('_sphinx_javascript_frameworks_compat.js').is_file()
+
+
 @pytest.mark.skipif(sphinx.version_info[:2] >= (6, 0),
                     reason="Requires Sphinx older than 6.0")
 def test_jquery_installed_sphinx_lt_60(blank_app):