Proposal for sphinxcontrib-jquery

docs/dev/design/sphinx-jquery.rst

@@ -0,0 +1,117 @@
+sphinxcontrib-jquery
+====================
+
+jQuery will be removed from Sphinx 6.0.0. We can expect 6.0.0 to ship in late 2022.
+
+.. seealso::
+
+    * https://github.com/sphinx-doc/sphinx/issues/7405
+    * https://github.com/sphinx-doc/sphinx/issues/10070
+    * https://github.com/readthedocs/sphinx-hoverxref/issues/160
+    * https://github.com/readthedocs/sphinx_rtd_theme/issues/1253
+    * https://github.com/pydata/pydata-sphinx-theme/issues/764
+
+This is a "request for comments" for a community-owned Sphinx extension that bundles jQuery.
+
+
+Overview
+--------
+
+Comment deadline:
+  November 1st, 2022
+
+Package-name:
+  ``sphinxcontrib-jquery``
+
+Python package:
+  ``sphinxcontrib.jquery``
+
+Dependencies:
+  Python 3+, Sphinx 1.8+ (or perhaps no lower bound?)
+
+Ownership:
+  Read the Docs core team will implement the initial releases of an otherwise community-owned package that lives in https://github.com/sphinx-contrib/jquery
+
+Functionality:
+  sphinxcontrib-jquery is a Sphinx extension that provides a simple mechanism for other Sphinx extensions and themes to ensure that jQuery is included into the HTML build outputs and loaded in the HTML DOM itself.
+  More specifically, the extension ensures that jQuery is loaded exactly once no matter how many themes and extensions that request to include jQuery nor the version of Sphinx.
+
+Scope:
+  This extension assumes that it's enough to provide a single version of jQuery for all of its dependent extensions and themes.
+  As the name implies, this extension is built to handle jQuery only.
+  It's not a general asset manager and it's not looking to do dependency resolution of jQuery versions.
+
+Usage
+-----
+
+The primary users of this package are
+**theme and extension developers** and
+**documentation project owners**.
+
+
+Theme and extension developers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following 2 steps need to be completed:
+
+#. A Sphinx theme or extension should depend on the python package ``sphinxcontrib-jquery``.
+#. In your extension's or theme's ``setup(app)``, call ``app.setup_extension("sphinxcontrib.jquery")``.
+
+In addition to this, we recommend extension and theme developers to log to the browser's ``console.error`` in case jQuery isn't found. The log message could for instance say::
+
+  if (typeof $ == "undefined") console.error("<package-name> depends on sphinxcontrib-jquery. Please ensure that <package-name>.setup(app) is called or add 'sphinxcontrib-jquery' to your conf.py extensions setting.")
+
+
+Documentation project owners
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you are depending on a theme or extension that did not itself address the removal of jQuery from Sphinx 6, you can patch up your project like this:
+
+#. Add ``sphinxcontrib-jquery`` to your installed dependencies.
+#. Add ``sphinxcontrib.jquery`` to your ``extensions`` setting in ``conf.py``.
+
+
+Calling ``app.setup_extension("sphinxcontrib.jquery")``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When a Sphinx theme or extension calls `setup_extension() <https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.setup_extension>`_, a call to ``sphinxcontrib.jquery.setup(app)`` will happen. Adding ``sphinxcontrib.jquery`` to a documentation project's ``conf.extensions`` will also call ``sphinxcontrib.jquery.setup(app)`` (at most once).
+
+In ``sphinxcontrib.jquery.setup(app)``, jQuery is added. The default behaviour is to detect the Sphinx version and include jQuery via `app.add_js_file <https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_js_file>`__ when Sphinx is from version 6 and up. jQuery is added at most once.
+
+
+Config value: ``jquery_force_enable``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When setting ``jquery_force_enable=True``, jQuery is added no matter the Sphinx version, but at most once. This is useful if you want to handle alternative conditions for adding jQuery.
+
+.. warning::
+
+  If you set ``jquery_force_enable=True``, you most likely should also add ``Sphinx>=6`` to your theme's/extension's dependencies since versions before this already bundles jQuery!
+
+
+jQuery version and inclusion
+----------------------------
+
+jQuery should be be shipped together with the Python package and not be referenced from a CDN.
+
+Sphinx has kept relatively up to date with jQuery, and this package intends to follow.
+The most recently bundled jQuery version was v3.5.1 and only two releases have happened since: 3.6.0 and 3.6.1.
+The 3.6.0 release had a very small backwards incompatibility which illustrates how harmless these upgrades are for the general purpose Sphinx package.
+
+Therefore, we propose to start the release of ``sphinxcontrib-jquery`` at 3.5.1 (the currently shipped version) and subsequently release 3.6.1 in an update. This will give users that need 3.5.1 a choice of a lower version.
+
+The bundled jQuery version will be NPM pre-minified and distributed together with the PyPI package.
+
+The minified jQuery JS file is ultimately included by calling `app.add_js_file <https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_js_file>`__, which is passed the following arguments:
+
+.. code:: python
+
+  app.add_js_file(
+      get_jquery_url_path(),
+      loading_method="defer",
+      priority=200,
+      integrity="sha256-{}".format(get_jquery_sha256_checksum())
+  )
+
+
+.. note:: It's possible to include jQuery in other ways, but this ultimately doesn't require this extension and is therefore not supported.