Merge pull request #245 from agriyakhetarpal/feat/no-execute-replite-kernel

Allow enabling/disabling REPL code execution in the `Replite` directive

Author: Carreau

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 executes when 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,50 @@ global value using an additional `:new_tab_button_text:` parameter:
    ax.plot(x, y)
    plt.show()
 ```
+
+````{tip}
+
+   With `jupyterlite-core` **versions 0.5.0 and later**, it is also possible to disable the execution of
+   the code in the Replite console by setting the `:execute:` option to `False`. This option defaults to `True`,
+   and setting it has no effect in versions prior to 0.5.0.
+
+   The behaviour can also be [configured globally](../configuration.md#replite-auto-execution-with-the-replite-directive)
+   and then overridden in individual directives as needed.
+
+```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()
+```
+
+````

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,
@@ -419,7 +423,15 @@ def run(self):
 
         search_params = search_params_parser(self.options.pop("search_params", False))
 
-        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", str(self.env.config.replite_auto_execute))
+
+        if execute not in ("True", "False"):
+            raise ValueError("The :execute: option must be either True or False")
+
+        if execute == "False":
+            self.options["execute"] = "0"
 
         content = self.content
 
@@ -430,6 +442,8 @@ def run(self):
             os.path.dirname(self.get_source_info()[0]),
         )
 
+        new_tab = self.options.pop("new_tab", False)
+
         if new_tab:
             directive_button_text = self.options.pop("new_tab_button_text", None)
             if directive_button_text is not None:
@@ -1155,6 +1169,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(