Add logic to enable deferring of script loading in output html

ascholerChemeketa · ascholerChemeketa · commit 224cfab6155b · 2021-07-16T14:00:03.000-07:00
Add logic to automatically defer webpack js files and scripts that Sphinx Bootstrap template adds
Add config variable to enable/disable the behavior
diff --git a/conf.py b/conf.py
@@ -319,6 +319,12 @@
 # This is the file name suffix for HTML files (e.g. ".xhtml").
 # html_file_suffix = None
 
+# It True, sets js files from Sphinx & Runestone to be loaded with defer attr
+# substantially speeding up page rendering. May cause issues with books that
+# have custom directives or raw html that assume jquery or another library
+# is loaded before body is parsed. 
+html_defer_js = True
+
 # Output file base name for HTML help builder.
 htmlhelp_basename = "PythonCoursewareProjectdoc"
 
diff --git a/runestone/__init__.py b/runestone/__init__.py
@@ -30,6 +30,7 @@
 import os, socket, pkg_resources
 import CodeChat.CodeToRest
 from sphinx.errors import ExtensionError
+from sphinx.builders.html import JavaScript
 
 
 # TODO: clean up - many of the folders are not needed as the files are imported by webpack
@@ -75,6 +76,26 @@ def runestone_extensions():
     modules.insert(0, modules.pop(modules.index("runestone.common")))
     return modules
 
+# setup_js_defer(app, pagename, templatexname, context, doctree)
+# -----------------------
+# Used to inspect js right before it is rendered to page so that
+# we can forcibly defer js files or prevent same
+def setup_js_defer(app, pagename, templatexname, context, doctree):
+    def js_defer(script_files):
+        for js in sorted(script_files):
+            if app.config.html_defer_js:
+                # Files added from Runestone should already have defer set - so just add it to sphinx based ones
+                to_defer = ["_static/jquery.js", "_static/underscore.js","_static/doctools.js"]
+                if isinstance(js, JavaScript) and js in to_defer:
+                    js.attributes["defer"] = ""
+            else:
+                #config flag not set, prevent all deferrals
+                if isinstance(js, JavaScript):
+                    js.attributes.pop("defer", None)
+        return ''
+
+    context['js_defer'] = js_defer
+
 
 # setup(app)
 # ----------
@@ -94,16 +115,18 @@ def setup(app):
 
     for jsfile in script_files:
         try:
-            app.add_autoversioned_javascript(jsfile)
+            app.add_autoversioned_javascript(jsfile, defer="")
         except ExtensionError:
-            app.add_js_file(jsfile)
+            app.add_js_file(jsfile, defer="")
     for cssfile in _css_files:
         try:
             app.add_autoversioned_stylesheet(cssfile)
         except ExtensionError:
             app.add_css_file(cssfile)
 
     app.config.html_static_path.append("dist/")
+    app.add_config_value("html_defer_js", False, 'env')
+    app.connect('html-page-context', setup_js_defer)
 
 
 def get_master_url():
diff --git a/runestone/common/project_template/_templates/plugin_layouts/sphinx_bootstrap/layout.html b/runestone/common/project_template/_templates/plugin_layouts/sphinx_bootstrap/layout.html
@@ -16,6 +16,12 @@
 <!DOCTYPE html>
 {%- endblock %}
 
+{%- block scripts %}
+{# Override the scripts block from sphinx so we can force loading of jquery/underscore/doctools js files #}
+{{ js_defer(script_files) }}
+{{ super() }}
+{%- endblock %}
+
 {# Sidebar: Rework into our Boostrap nav section. #}
 {% macro navBar() %}
 
diff --git a/runestone/common/project_template/conf.tmpl b/runestone/common/project_template/conf.tmpl
@@ -275,6 +275,12 @@ html_show_sourcelink = False
 # This is the file name suffix for HTML files (e.g. ".xhtml").
 #html_file_suffix = None
 
+# It True, sets js files from Sphinx & Runestone to be loaded with defer attr
+# substantially speeding up page rendering. May cause issues with books that
+# have custom directives or raw html that assume jquery or another library
+# is loaded before body is parsed. 
+html_defer_js = True
+
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'PythonCoursewareProjectdoc'
 
diff --git a/runestone/common/runestonedirective.py b/runestone/common/runestonedirective.py
@@ -175,8 +175,8 @@ def _add_autoversion(
 
 
 # Convenience method to call ``add_js_file`` using ``add_autoversion``.
-def _add_autoversioned_javascript(self, filename):
-    return self.add_js_file(self.add_autoversion(filename))
+def _add_autoversioned_javascript(self, filename, **kwargs):
+    return self.add_js_file(self.add_autoversion(filename), **kwargs)
 
 
 # Convenience method for calling ``add_css_file`` using ``add_autoversion``.
