✨ IMPROVE: Conditionally load on pages (#30)

Author: choldgraf

docs/changelog.md

@@ -4,4 +4,4 @@
 
 ### Updates
 
-- `sphinx-thebe` now uses the correct and latest version of thebe, since it has been renamed from `thebelab` to `thebe`.
+- `sphinx-thebe` now uses the correct and latest version of thebe, since it has been renamed from `thebelab` to `thebe`.

docs/conf.py

@@ -50,7 +50,7 @@
     # "codemirror-theme": "blackboard"  # Doesn't currently work
 }
 
-myst_admonition_enable = True
+myst_enable_extensions = ["colon_fence"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

docs/use.md

@@ -6,7 +6,8 @@ There are two steps to using `sphinx-thebe`. First, you must mark certain
 parts of your page as "ready for thebe". Next, you must insert a button onto
 the page to tell Thebe to initialize.
 
-:::{admonition,tip} Using reStructuredText vs. MyST Markdown
+:::{admonition} Using reStructuredText vs. MyST Markdown
+:class: tip
 The examples on this page use **MyST Markdown syntax**, a form of markdown that works with Sphinx directives. You can also use reStructuredText if you wish. For information about reStructuredText vs. MyST Markdown, see [the MyST Parser documentation](https://myst-parser.readthedocs.io/en/latest/using/syntax.html) as well as [](examples/rst) for some tips.
 :::
 

setup.py

@@ -27,7 +27,7 @@
         "sphinx_thebe": ["_static/sphinx-thebe.css", "_static/sphinx-thebe.js",]
     },
     classifiers=["License :: OSI Approved :: MIT License"],
-    install_requires=["sphinx>=1.8"],
+    install_requires=["sphinx>=3.5,<5"],
     extras_require={
         "sphinx": [
             "myst-parser[sphinx]",

sphinx_thebe/__init__.py

@@ -30,12 +30,25 @@ def init_thebe_default_config(app, env, docnames):
             thebe_config[key] = val
 
 
-def init_thebe_core(app, env):
-    config_thebe = app.config["thebe_config"]
+def _check_if_load_thebe(doctree, config_thebe):
+    """Decide whether to load thebe based on the page's context."""
+    # Only load `thebe` if there is a thebe button somewhere
+    if not doctree or (not doctree.traverse(ThebeButtonNode)):
+        return
+
     if not config_thebe:
         logger.warning("Didn't find `thebe_config` in conf.py, add to use thebe")
         return
 
+    return True
+
+
+def init_thebe_core(app, pagename, templatename, context, doctree):
+    """Load thebe assets if there's a thebe button on this page."""
+    config_thebe = app.config["thebe_config"]
+    if not _check_if_load_thebe(doctree, config_thebe):
+        return
+
     # Add core libraries
     opts = {"async": "async"}
     app.add_js_file(filename="https://unpkg.com/thebe@latest/lib/index.js", **opts)
@@ -53,7 +66,7 @@ def init_thebe_core(app, env):
 def update_thebe_context(app, doctree, docname):
     """Add thebe config nodes to this doctree."""
     config_thebe = app.config["thebe_config"]
-    if not config_thebe:
+    if not _check_if_load_thebe(doctree, config_thebe):
         return
 
     # Thebe configuration
@@ -191,9 +204,10 @@ def setup(app):
     # Set default values for the configuration
     app.connect("env-before-read-docs", init_thebe_default_config)
 
-    # Include Thebe core docs
+    # Update the doctree with thebe-specific information if needed
     app.connect("doctree-resolved", update_thebe_context)
-    app.connect("env-updated", init_thebe_core)
+    # Load the JS/CSS assets for thebe if needed    
+    app.connect("html-page-context", init_thebe_core)
 
     # configuration for this tool
     app.add_config_value("thebe_config", {}, "html")