Allow enabling/disabling REPL code execution in the Replite directive

docs/configuration.md

@@ -85,6 +85,12 @@ voici_new_tab_button_text = "My custom Voici button text"
 You can override this text on a per-directive basis by passing the `:new_tab_button_text:` option
 to the directive. Note that this is compatible only if `:new_tab:` is also provided.
 
+## REPL code auto-execution with the `Replite` directive
+
+It is possible to control whether code snippets in REPL environments automatically executeswhen loaded.
+For this, you may set `replite_auto_execute = False` globally in `conf.py` with  (defaults to `True` if
+not present), or override it on a per-directive basis  with `:execute: true` or `:execute: false`.
+
 ## Strip particular tagged cells from IPython Notebooks
 
 When using the `NotebookLite`, `JupyterLite`, or `Voici` directives with a notebook passed to them, you can

docs/directives/replite.md

@@ -110,3 +110,44 @@ global value using an additional `:new_tab_button_text:` parameter:
    ax.plot(x, y)
    plt.show()
 ```
+
+It is also possible to disable the execution of the code in the Replite console by setting the `:execute:` option to `False`:
+
+```rst
+.. replite::
+   :kernel: xeus-python
+   :new_tab: True # False works too
+   :new_tab_button_text: Open REPL with the code execution disabled
+   :execute: False
+
+   import matplotlib.pyplot as plt
+   import numpy as np
+
+   x = np.linspace(0, 2 * np.pi, 200)
+   y = np.sin(x)
+
+   fig, ax = plt.subplots()
+   ax.plot(x, y)
+   plt.show()
+```
+
+```{eval-rst}
+.. replite::
+   :kernel: xeus-python
+   :new_tab: True # False works too
+   :new_tab_button_text: Open REPL with the code execution disabled
+   :execute: False
+
+   import matplotlib.pyplot as plt
+   import numpy as np
+
+   x = np.linspace(0, 2 * np.pi, 200)
+   y = np.sin(x)
+
+   fig, ax = plt.subplots()
+   ax.plot(x, y)
+   plt.show()
+```
+
+The behaviour can also be [configured globally](../configuration.md#replite-auto-execution-with-the-replite-directive)
+and then overridden in individual directives.

jupyterlite_sphinx/jupyterlite_sphinx.py

@@ -269,6 +269,9 @@ def __init__(
             code = "\n".join(code_lines)
             lite_options["code"] = code
 
+        if "execute" in lite_options and lite_options["execute"] == "0":
+            lite_options["execute"] = "0"
+
         app_path = self.lite_app
         if notebook is not None:
             lite_options["path"] = notebook
@@ -401,6 +404,7 @@ class RepliteDirective(SphinxDirective):
         "width": directives.unchanged,
         "height": directives.unchanged,
         "kernel": directives.unchanged,
+        "execute": directives.unchanged,
         "toolbar": directives.unchanged,
         "theme": directives.unchanged,
         "prompt": directives.unchanged,
@@ -421,6 +425,17 @@ def run(self):
 
         new_tab = self.options.pop("new_tab", False)
 
+        # We first check the global config, and then the per-directive
+        # option. It defaults to true for backwards compatibility.
+        execute = self.options.pop("execute", None)
+        if execute is None:
+            execute = str(self.env.config.replite_auto_execute).lower()
+        else:
+            execute = execute.lower()
+
+        if execute == "false":
+            self.options["execute"] = "0"
+
         content = self.content
 
         button_text = None
@@ -1155,6 +1170,7 @@ def setup(app):
         man=(skip, None),
     )
     app.add_directive("replite", RepliteDirective)
+    app.add_config_value("replite_auto_execute", True, rebuild="html")
 
     # Initialize Voici directive and tabbed interface
     app.add_node(

pyproject.toml

@@ -16,7 +16,9 @@ dependencies = [
     "docutils",
     "jupyter_server",
     "jupyterlab_server",
-    "jupyterlite-core >=0.2,<0.6",
+    # temporary: for trying out no-code-run REPL.
+    # wait for 0.5.0 stable release
+    "jupyterlite-core==0.5.0b0",
     "jupytext",
     "nbformat",
     "sphinx>=4",