Add configuration to improve large page experience (#227)

* Change tooltipster application strategy to support large pages

Use dynamic application of the tooltipsterification process to create it, then open it, on click or hover rather than processing potentially thousands of elements during the page load event.

The tooltipster docs suggest that this is a less performant strategy (I expect very small hiccups on hover), but for large pages it is much more preferable than a second-long load delay.

This will be refactored later into an option

* Revert "Change tooltipster application strategy to support large pages"

This reverts commit 8c36803.

* Add new configuration `hoverxref_tooltip_lazy` to support large pages efficiently

* Correct docs to appropriately match function and add clarity

as suggested

* Rework hoverxref_tooltip_lazy if statements to be cleaner

* Add tests for hoverxref_tooltip_lazy option

Co-authored-by: Manuel Kaufmann <[email protected]>

Author: bast0006

docs/configuration.rst

@@ -177,6 +177,16 @@ These settings have effect only in tooltips.
    Type: string
 
 
+.. confval:: hoverxref_tooltip_lazy
+   Description: Whether to lazily generate tooltips (insert the HTML for the tooltip on hover, rather than on page load).
+   This is known to be slower, but prevents the browser from stalling on load for very big doc pages.
+   We recommend you keeping it as `False` unless you are experiencing page load issues.
+
+   Default ``False``
+
+   Type: bool
+
+
 .. warning::
 
    The following settings are passed directly to Tooltipster_.

hoverxref/_static/js/hoverxref.js_t

@@ -91,14 +91,8 @@ function getEmbedURL(url) {
     return url
 }
 
-
-$(document).ready(function() {
-    // Remove ``title=`` attribute for intersphinx nodes that have hoverxref enabled.
-    // It doesn't make sense the browser shows the default tooltip (browser's built-in)
-    // and immediately after that our tooltip was shown.
-    $('.{{ hoverxref_css_class_prefix }}hoverxref.external').each(function () { $(this).removeAttr('title') });
-
-    $('.{{ hoverxref_css_class_prefix }}hoverxref.{{ hoverxref_css_class_prefix }}tooltip').tooltipster({
+function addTooltip(target) {
+    return target.tooltipster({
         theme: {{ hoverxref_tooltip_theme }},
         interactive: {{ 'true' if hoverxref_tooltip_interactive else 'false' }},
         maxWidth: {{ hoverxref_tooltip_maxwidth }},
@@ -144,6 +138,33 @@ $(document).ready(function() {
             );
         }
     })
+}
+
+
+$(document).ready(function() {
+    // Remove ``title=`` attribute for intersphinx nodes that have hoverxref enabled.
+    // It doesn't make sense the browser shows the default tooltip (browser's built-in)
+    // and immediately after that our tooltip was shown.
+
+    // Support lazy-loading here by switching between on-page-load (calling .tooltipster directly)
+    // or delaying it until after a mouseenter or click event.
+    // On large pages (the use case for lazy-loaded tooltipster) this moves dom manipulation to
+    // on-interaction, which is known to be less performant on small pages (as per tooltipster docs),
+    // but on massive docs pages fixes an otherwise severe page load stall when tooltipster
+    // manipulates the html for every single tooltip at once.
+    {% if hoverxref_tooltip_lazy %}
+    $('.{{ hoverxref_css_class_prefix }}hoverxref.{{ hoverxref_css_class_prefix }}tooltip').one('mouseenter click touchstart tap', function(event) {
+        $(this).removeAttr('title');
+        {# If we're lazy-tipstering, we've used up the click event, so open the modal too with tooltipster('open') #}
+        addTooltip($(this)).tooltipster('open');
+    });
+    {% else %}
+    $('.{{ hoverxref_css_class_prefix }}hoverxref.external').each(function () { $(this).removeAttr('title') });
+    addTooltip(
+        $('.{{ hoverxref_css_class_prefix }}hoverxref.{{ hoverxref_css_class_prefix }}tooltip')
+    )
+    {% endif %}
+
 
     var modalHtml = `
   <div class="modal micromodal-slide {{ hoverxref_modal_class }}" id="micromodal" aria-hidden="true">

hoverxref/extension.py

@@ -351,6 +351,7 @@ def setup(app):
     app.add_config_value('hoverxref_intersphinx_types', {}, 'env')
     app.add_config_value('hoverxref_api_host', 'https://readthedocs.org', 'env')
     app.add_config_value('hoverxref_sphinx_version', sphinx.__version__, 'env')
+    app.add_config_value('hoverxref_tooltip_lazy', False, 'env')
 
     # Tooltipster settings
     # Deprecated in favor of ``hoverxref_api_host``

tests/test_jsconf.py

@@ -0,0 +1,54 @@
+import pytest
+
+from .utils import srcdir
+
+
+@pytest.mark.sphinx(
+    srcdir=srcdir,
+    confoverrides={
+        'hoverxref_tooltip_lazy': True,
+    },
+)
+def test_lazy_tooltips(app, status, warning):
+    app.build()
+    path = app.outdir / '_static/js/hoverxref.js'
+    assert path.exists() is True
+    content = open(path).read()
+
+    chunks = [
+        ".one('mouseenter click touchstart tap', function(event) {",
+        ".tooltipster('open');",
+    ]
+
+    for chunk in chunks:
+        assert chunk in content
+
+    ignored_chunks = [
+        ".each(function () { $(this).removeAttr('title') });",
+    ]
+    for chunk in ignored_chunks:
+        assert chunk not in content
+
+
+@pytest.mark.sphinx(
+    srcdir=srcdir,
+)
+def test_lazy_tooltips_notlazy(app, status, warning):
+    app.build()
+    path = app.outdir / '_static/js/hoverxref.js'
+    assert path.exists() is True
+    content = open(path).read()
+
+    chunks = [
+        ".each(function () { $(this).removeAttr('title') });",
+    ]
+
+    for chunk in chunks:
+        assert chunk in content
+
+    ignored_chunks = [
+        ".one('mouseenter click touchstart tap', function(event) {",
+        ".tooltipster('open');",
+    ]
+    for chunk in ignored_chunks:
+        assert chunk not in content