diff --git a/docs/configuration.md b/docs/configuration.md index fb73d52..7ff1b1d 100644 --- a/docs/configuration.md +++ b/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 diff --git a/docs/directives/replite.md b/docs/directives/replite.md index 1bbd634..26f115f 100644 --- a/docs/directives/replite.md +++ b/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() +``` + +```` diff --git a/jupyterlite_sphinx/jupyterlite_sphinx.py b/jupyterlite_sphinx/jupyterlite_sphinx.py index 36bddec..2ae89f3 100644 --- a/jupyterlite_sphinx/jupyterlite_sphinx.py +++ b/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(