From abbac9918ff46853d2ea1f6ee9f0be9572252194 Mon Sep 17 00:00:00 2001
From: Benjamin Bach <benjamin@readthedocs.org>
Date: Tue, 24 Jan 2023 15:44:19 +0100
Subject: [PATCH 1/5] Add configuration option `jquery_cors_enable` and bump to
 4.0.0

---
 CHANGES.rst                      |  9 +++++++++
 README.rst                       |  9 +++++++++
 sphinxcontrib/jquery/__init__.py | 22 ++++++++++++++++++----
 tests/test_jquery_installed.py   | 18 +++++++++++++++++-
 4 files changed, 53 insertions(+), 5 deletions(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index 79d6d3e..850fdb9 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -1,3 +1,12 @@
+Release 4.0.0 (24/01/2023)
+==========================
+
+* Enforcing CORS check breaks documentation builds displayed directly from local filesystem (``file:///``).
+  Make CORS checks optional with setting ``jquery_cors_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)
 ==========================
 
diff --git a/README.rst b/README.rst
index 7e955b6..ddbee61 100644
--- a/README.rst
+++ b/README.rst
@@ -19,3 +19,12 @@ To use it, add ``sphinxcontrib.jquery`` as a Sphinx extension:
        "sphinxcontrib.jquery",
    ]
    ...
+
+Configuration
+-------------
+
+```
+# Enable CORS integrity="<hash>" on included JS files
+# Default: False
+jquery_cors_enable = True
+```
diff --git a/sphinxcontrib/jquery/__init__.py b/sphinxcontrib/jquery/__init__.py
index f38224f..578b4e5 100644
--- a/sphinxcontrib/jquery/__init__.py
+++ b/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 CORS because it does not trigger the hash
+            # check but instead blocks the request when viewing documentation locally
+            # through the file:// "protocol".
+            if config.jquery_cors_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 CORS checks
+    app.add_config_value("jquery_cors_enable", default=False, rebuild="html", types=[bool])
+
+    app.connect('config-inited', add_js_files)
+
     return {
         "parallel_read_safe": True,
         "parallel_write_safe": True,
diff --git a/tests/test_jquery_installed.py b/tests/test_jquery_installed.py
index 92e9fdc..9d7eff4 100644
--- a/tests/test_jquery_installed.py
+++ b/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_cors_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):

From 339baa374a28c4a84c76812f186807c3ba1277bf Mon Sep 17 00:00:00 2001
From: Benjamin Bach <benjamin@overtag.dk>
Date: Mon, 30 Jan 2023 11:09:31 +0100
Subject: [PATCH 2/5] Rename CORS to SRI since it's SRI-specific

---
 CHANGES.rst                      | 4 ++--
 README.rst                       | 7 +++++--
 sphinxcontrib/jquery/__init__.py | 8 ++++----
 tests/test_jquery_installed.py   | 2 +-
 4 files changed, 12 insertions(+), 9 deletions(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index 850fdb9..96e68ea 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -1,8 +1,8 @@
 Release 4.0.0 (24/01/2023)
 ==========================
 
-* Enforcing CORS check breaks documentation builds displayed directly from local filesystem (``file:///``).
-  Make CORS checks optional with setting ``jquery_cors_enable``, default is ``False``.
+* 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
diff --git a/README.rst b/README.rst
index ddbee61..cabf5b5 100644
--- a/README.rst
+++ b/README.rst
@@ -24,7 +24,10 @@ Configuration
 -------------
 
 ```
-# Enable CORS integrity="<hash>" on included JS files
+# 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_cors_enable = True
+
+jquery_sri_enable = True
 ```
diff --git a/sphinxcontrib/jquery/__init__.py b/sphinxcontrib/jquery/__init__.py
index 578b4e5..91fb6ef 100644
--- a/sphinxcontrib/jquery/__init__.py
+++ b/sphinxcontrib/jquery/__init__.py
@@ -25,10 +25,10 @@ def add_js_files(app, config):
     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:
-            # The default is not not enable CORS because it does not trigger the hash
+            # 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_cors_enable:
+            if config.jquery_sri_enable:
                 app.add_js_file(filename, integrity=integrity, priority=100)
             else:
                 app.add_js_file(filename, priority=100)
@@ -40,8 +40,8 @@ def add_js_files(app, config):
 
 
 def setup(app):
-    # Configuration value for enabling CORS checks
-    app.add_config_value("jquery_cors_enable", default=False, rebuild="html", types=[bool])
+    # 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)
 
diff --git a/tests/test_jquery_installed.py b/tests/test_jquery_installed.py
index 9d7eff4..cfe05d4 100644
--- a/tests/test_jquery_installed.py
+++ b/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"], "jquery_cors_enable": True})
+    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 '

From f71101976183b4a47caf52ab090ee326199287bd Mon Sep 17 00:00:00 2001
From: Benjamin Bach <benjamin@overtag.dk>
Date: Wed, 8 Feb 2023 22:41:47 +0100
Subject: [PATCH 3/5] md=>rest

---
 README.rst | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/README.rst b/README.rst
index cabf5b5..541fcb4 100644
--- a/README.rst
+++ b/README.rst
@@ -20,14 +20,16 @@ To use it, add ``sphinxcontrib.jquery`` as a Sphinx extension:
    ]
    ...
 
+
 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
+.. code:: python
+
+    # 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
 
-jquery_sri_enable = True
-```

From a2e55a10fa45a8c1316e509473712ad3cf730827 Mon Sep 17 00:00:00 2001
From: Benjamin Bach <benjamin@overtag.dk>
Date: Wed, 8 Feb 2023 22:43:55 +0100
Subject: [PATCH 4/5] jquery_sri_enable => jquery_use_sri

---
 sphinxcontrib/jquery/__init__.py | 4 ++--
 tests/test_jquery_installed.py   | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/sphinxcontrib/jquery/__init__.py b/sphinxcontrib/jquery/__init__.py
index 91fb6ef..339ef48 100644
--- a/sphinxcontrib/jquery/__init__.py
+++ b/sphinxcontrib/jquery/__init__.py
@@ -28,7 +28,7 @@ def add_js_files(app, config):
             # 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:
+            if config.jquery_use_sri:
                 app.add_js_file(filename, integrity=integrity, priority=100)
             else:
                 app.add_js_file(filename, priority=100)
@@ -41,7 +41,7 @@ def add_js_files(app, config):
 
 def setup(app):
     # Configuration value for enabling SRI checks
-    app.add_config_value("jquery_sri_enable", default=False, rebuild="html", types=[bool])
+    app.add_config_value("jquery_use_sri", default=False, rebuild="html", types=[bool])
 
     app.connect('config-inited', add_js_files)
 
diff --git a/tests/test_jquery_installed.py b/tests/test_jquery_installed.py
index cfe05d4..5ede54a 100644
--- a/tests/test_jquery_installed.py
+++ b/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"], "jquery_sri_enable": True})
+    out_dir = blank_app(confoverrides={"extensions": ["sphinxcontrib.jquery"], "jquery_use_sri": True})
 
     text = out_dir.joinpath("index.html").read_text(encoding="utf-8")
     assert ('<script '

From 3b19dc88800d3d30ce2588680b570e159c03dcd1 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Tue, 14 Mar 2023 12:41:50 +0000
Subject: [PATCH 5/5] Documentation updates

---
 CHANGES.rst                      |  8 +++++---
 README.rst                       | 22 ++++++++++++++++------
 sphinxcontrib/jquery/__init__.py | 13 +++++++------
 tests/test_jquery_installed.py   |  2 +-
 4 files changed, 29 insertions(+), 16 deletions(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index 96e68ea..26f9179 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -1,9 +1,11 @@
 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`_.
+* Enforcing `subresource integrity`_ (SRI) checks breaks loading rendered
+  documentation from local filesystem (``file:///`` URIs).
+  SRI checks may now be configured by the boolean configuration option
+  ``jquery_use_sri``, which defaults to ``False``.
+  See `sphinx_rtd_theme#1420`_ for further details.
 
 .. _sphinx_rtd_theme#1420: https://github.com/readthedocs/sphinx_rtd_theme/issues/1420
 
diff --git a/README.rst b/README.rst
index 541fcb4..50e365a 100644
--- a/README.rst
+++ b/README.rst
@@ -24,12 +24,22 @@ To use it, add ``sphinxcontrib.jquery`` as a Sphinx extension:
 Configuration
 -------------
 
-.. code:: python
+.. As this is a README, we restrict the directives we use to those which GitHub
+   renders correctly. This means that we cannot use ``versionadded``,
+   ``confval``, ``warning``, or other similar directives.
+   We use a reStructuredText definition list to emulate the ``confval``
+   rendering.
+   We use inline **bold** syntax as a poor-man's ``.. warning::`` directive.
+
+``jquery_use_sri``
+   A boolean value controlling whether to enable  `subresource integrity`_ (SRI)
+   checks for JavaScript files that this extension loads.
+
+   The default is ``False``.
 
-    # 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
+   **Warning**: Enabling SRI checks may break documentation when loaded from
+   local filesystem (``file:///`` URIs).
 
-    jquery_sri_enable = True
+   *New in version 4.0.*
 
+   .. _subresource integrity: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
diff --git a/sphinxcontrib/jquery/__init__.py b/sphinxcontrib/jquery/__init__.py
index 339ef48..3ac504a 100644
--- a/sphinxcontrib/jquery/__init__.py
+++ b/sphinxcontrib/jquery/__init__.py
@@ -25,11 +25,11 @@ def add_js_files(app, config):
     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:
-            # 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".
+            # The default is not to enable subresource integrity checks, as it
+            # does not trigger the hash check but instead blocks the request
+            # when viewing documentation locally through the ``file://`` URIs.
             if config.jquery_use_sri:
-                app.add_js_file(filename, integrity=integrity, priority=100)
+                app.add_js_file(filename, priority=100, integrity=integrity)
             else:
                 app.add_js_file(filename, priority=100)
             shutil.copyfile(
@@ -40,8 +40,9 @@ def add_js_files(app, config):
 
 
 def setup(app):
-    # Configuration value for enabling SRI checks
-    app.add_config_value("jquery_use_sri", default=False, rebuild="html", types=[bool])
+    # Configuration value for enabling `subresource integrity`__ (SRI) checks
+    # __ https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
+    app.add_config_value("jquery_use_sri", default=False, rebuild="html", types=(bool,))
 
     app.connect('config-inited', add_js_files)
 
diff --git a/tests/test_jquery_installed.py b/tests/test_jquery_installed.py
index 5ede54a..38e05e6 100644
--- a/tests/test_jquery_installed.py
+++ b/tests/test_jquery_installed.py
@@ -31,7 +31,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):
+def test_jquery_installed_sphinx_ge_60_use_sri(blank_app):
     out_dir = blank_app(confoverrides={"extensions": ["sphinxcontrib.jquery"], "jquery_use_sri": True})
 
     text = out_dir.joinpath("index.html").read_text(encoding="utf-8")