Add a new-tabbed variant for the Replite directive and clean up new tab button text configuration (#228)

* Add Replite tabbed variant

* Add docs on using `:new_tab:` for Replite

* Add docs on global value and overrides for Replite buttons

* Rename `:button_text:` to `:new_tab_button_text:`

* Add "_new_tab_" to button text config options

Author: agriyakhetarpal

docs/configuration.md

@@ -67,21 +67,22 @@ jupyterlite_config = "jupyter_lite_config.json"
 jupyterlite_overrides = "overrides.json"
 ```
 
-# Setting default button texts for the `JupyterLite`, `NotebookLite`, and `Voici` directives
+# Setting default button texts for the `JupyterLite`, `NotebookLite`, `Replite`, and `Voici` directives
 
-When using the `:new_tab:` option in the `JupyterLite`, `NotebookLite`, and `Voici` directives,
-the button text defaults to "Open as a notebook" and "Open with Voici", respectively.
+When using the `:new_tab:` option in the `JupyterLite`, `NotebookLite`, `Replite`, and `Voici` directives,
+the button text defaults to "Open as a notebook", "Open in a REPL", and "Open with Voici", respectively.
 
 You can optionally the button text on a global level for these directives by setting the
 following values in your `conf.py` file:
 
 ```python
-jupyterlite_button_text = "My custom JupyterLite button text"
-notebooklite_button_text = "My custom NotebookLite button text"
-voici_button_text = "My custom Voici button text"
+jupyterlite_new_tab_button_text = "My custom JupyterLite button text"
+notebooklite_new_tab_button_text = "My custom NotebookLite button text"
+replite_new_tab_button_text = "My custom Replite button text"
+voici_new_tab_button_text = "My custom Voici button text"
 ```
 
-You can override this text on a per-directive basis by passing the `:button_text:` option
+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.
 
 ## Strip particular tagged cells from IPython Notebooks

docs/directives/jupyterlite.md

@@ -51,18 +51,18 @@ of JupyterLite.
 ```
 
 When using this option, it is also possible to customise the button text, overriding the
-global value using an additional `:button_text:` parameter:
+global value using an additional `:new_tab_button_text:` parameter:
 
 ```rst
 .. jupyterlite:: my_notebook.ipynb
    :new_tab: True
-   :button_text: My custom JupyterLite button text
+   :new_tab_button_text: My custom JupyterLite button text
 ```
 
 ```{eval-rst}
 .. jupyterlite:: my_notebook.ipynb
    :new_tab: True
-   :button_text: My custom JupyterLite button text
+   :new_tab_button_text: My custom JupyterLite button text
 ```
 
 ## Search parameters

docs/directives/notebooklite.md

@@ -47,16 +47,16 @@ Lab interface.
 ```
 
 When using this option, it is also possible to customise the button text, overriding the
-global value using an additional `:button_text:` parameter:
+global value using an additional `:new_tab_button_text:` parameter:
 
 ```rst
 .. notebooklite:: my_notebook.ipynb
    :new_tab: True
-   :button_text: My custom NotebookLite button text
+   :new_tab_button_text: My custom NotebookLite button text
 ```
 
 ```{eval-rst}
 .. notebooklite:: my_notebook.ipynb
    :new_tab: True
-   :button_text: My custom NotebookLite button text
+   :new_tab_button_text: My custom NotebookLite button text
 ```

docs/directives/replite.md

@@ -38,3 +38,75 @@ This directive takes extra options which are the same options as the `replite` p
    ax.plot(x, y)
    plt.show()
 ```
+
+If you use the `:new_tab:` option in the directive, the Replite console will be opened in a new browser tab
+with the code pre-filled.
+
+```rst
+.. replite::
+   :kernel: xeus-python
+   :new_tab: True
+
+   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
+
+   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()
+```
+
+When using this option, it is also possible to customise the button text, overriding the
+global value using an additional `:new_tab_button_text:` parameter:
+
+```rst
+.. replite::
+   :kernel: xeus-python
+   :new_tab: True
+   :new_tab_button_text: My custom Replite button text
+
+   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
+   :new_tab_button_text: My custom Replite button text
+
+   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()
+```

docs/directives/voici.md

@@ -42,16 +42,16 @@ the notebook in a new browser tab, instead of in the current page.
 ```
 
 When using this option, it is also possible to customise the button text, overriding the
-global value using an additional `:button_text:` parameter:
+global value using an additional `:new_tab_button_text:` parameter:
 
 ```rst
 .. voici:: my_notebook.ipynb
    :new_tab: True
-   :button_text: My custom Voici button text
+   :new_tab_button_text: My custom Voici button text
 ```
 
 ```{eval-rst}
 .. voici:: my_notebook.ipynb
    :new_tab: True
-   :button_text: My custom Voici button text
+   :new_tab_button_text: My custom Voici button text
 ```

jupyterlite_sphinx/jupyterlite_sphinx.py

@@ -236,6 +236,66 @@ class NotebookLiteTab(BaseNotebookTab):
     notebooks_path = "../notebooks/"
 
 
+# We do not inherit from _InTab here because Replite
+# has a different URL structure and we need to ensure
+# that the code is serialised to be passed to the URL.
+class RepliteTab(Element):
+    """Appended to the doctree by the RepliteDirective directive
+
+    Renders a button that opens a REPL with JupyterLite in a new tab.
+    """
+
+    lite_app = "repl/"
+    notebooks_path = ""
+
+    def __init__(
+        self,
+        rawsource="",
+        *children,
+        prefix=JUPYTERLITE_DIR,
+        content=[],
+        notebook=None,
+        lite_options={},
+        button_text=None,
+        **attributes,
+    ):
+        # For a new-tabbed variant, we need to ensure we process the content
+        # into properly encoded code for passing it to the URL.
+        if content:
+            code_lines: list[str] = [
+                "" if not line.strip() else line for line in content
+            ]
+            code = "\n".join(code_lines)
+            lite_options["code"] = code
+
+        app_path = self.lite_app
+        if notebook is not None:
+            lite_options["path"] = notebook
+            app_path = f"{self.lite_app}{self.notebooks_path}"
+
+        options = "&".join(
+            [f"{key}={quote(value)}" for key, value in lite_options.items()]
+        )
+
+        self.lab_src = (
+            f'{prefix}/{app_path}{f"index.html?{options}" if options else ""}'
+        )
+
+        self.button_text = button_text
+
+        super().__init__(
+            rawsource,
+            **attributes,
+        )
+
+    def html(self):
+        return (
+            '<button class="try_examples_button" '
+            f"onclick=\"window.open('{self.lab_src}')\">"
+            f"{self.button_text}</button>"
+        )
+
+
 class NotebookLiteIframe(_LiteIframe):
     """Appended to the doctree by the NotebookliteDirective directive
 
@@ -345,6 +405,8 @@ class RepliteDirective(SphinxDirective):
         "prompt": directives.unchanged,
         "prompt_color": directives.unchanged,
         "search_params": directives.unchanged,
+        "new_tab": directives.unchanged,
+        "new_tab_button_text": directives.unchanged,
     }
 
     def run(self):
@@ -356,19 +418,45 @@ def run(self):
 
         search_params = search_params_parser(self.options.pop("search_params", False))
 
+        new_tab = self.options.pop("new_tab", False)
+
+        content = self.content
+
+        button_text = None
+
         prefix = os.path.relpath(
             os.path.join(self.env.app.srcdir, JUPYTERLITE_DIR),
             os.path.dirname(self.get_source_info()[0]),
         )
 
+        if new_tab:
+            directive_button_text = self.options.pop("new_tab_button_text", None)
+            if directive_button_text is not None:
+                button_text = directive_button_text
+            else:
+                button_text = self.env.config.replite_new_tab_button_text
+            return [
+                RepliteTab(
+                    prefix=prefix,
+                    width=width,
+                    height=height,
+                    prompt=prompt,
+                    prompt_color=prompt_color,
+                    content=content,
+                    search_params=search_params,
+                    lite_options=self.options,
+                    button_text=button_text,
+                )
+            ]
+
         return [
             RepliteIframe(
                 prefix=prefix,
                 width=width,
                 height=height,
                 prompt=prompt,
                 prompt_color=prompt_color,
-                content=self.content,
+                content=content,
                 search_params=search_params,
                 lite_options=self.options,
             )
@@ -387,7 +475,7 @@ class _LiteDirective(SphinxDirective):
         "prompt_color": directives.unchanged,
         "search_params": directives.unchanged,
         "new_tab": directives.unchanged,
-        "button_text": directives.unchanged,
+        "new_tab_button_text": directives.unchanged,
     }
 
     def run(self):
@@ -451,24 +539,19 @@ def run(self):
             notebook_name = None
 
         if new_tab:
-            directive_button_text = self.options.pop("button_text", None)
+            directive_button_text = self.options.pop("new_tab_button_text", None)
             if directive_button_text is not None:
                 button_text = directive_button_text
             else:
                 # If none, we use the appropriate global config based on
                 # the type of directive passed.
                 if isinstance(self, JupyterLiteDirective):
-                    button_text = self.env.config.jupyterlite_button_text
+                    button_text = self.env.config.jupyterlite_new_tab_button_text
                 elif isinstance(self, NotebookLiteDirective):
-                    button_text = self.env.config.notebooklite_button_text
+                    button_text = self.env.config.notebooklite_new_tab_button_text
                 elif isinstance(self, VoiciDirective):
-                    button_text = self.env.config.voici_button_text
-        elif "button_text" in self.options:
-            raise ValueError(
-                "'button_text' is only valid if 'new_tab' is True. To modify the prompt text, use 'prompt' and 'prompt_color'."
-            )
+                    button_text = self.env.config.voici_new_tab_button_text
 
-        if new_tab:
             return [
                 self.newtab_cls(
                     prefix=prefix,
@@ -511,9 +594,9 @@ class BaseJupyterViewDirective(_LiteDirective):
         "prompt_color": directives.unchanged,
         "search_params": directives.unchanged,
         "new_tab": directives.unchanged,
-        # "button_text" below is valid only if "new_tab" is True, otherwise
+        # "new_tab_button_text" below is useful only if "new_tab" is True, otherwise
         # we have "prompt" and "prompt_color" as options already.
-        "button_text": directives.unchanged,
+        "new_tab_button_text": directives.unchanged,
     }
 
 
@@ -927,15 +1010,18 @@ def setup(app):
         rebuild="html",
     )
 
-    # Allow customising the button text for each directive (only when "new_tab" is True,
-    # error otherwise)
+    # Allow customising the button text for each directive (this is useful
+    # only when "new_tab" is set to True)
+    app.add_config_value(
+        "jupyterlite_new_tab_button_text", "Open as a notebook", rebuild="html"
+    )
     app.add_config_value(
-        "jupyterlite_button_text", "Open as a notebook", rebuild="html"
+        "notebooklite_new_tab_button_text", "Open as a notebook", rebuild="html"
     )
+    app.add_config_value("voici_new_tab_button_text", "Open with Voici", rebuild="html")
     app.add_config_value(
-        "notebooklite_button_text", "Open as a notebook", rebuild="html"
+        "replite_new_tab_button_text", "Open in a REPL", rebuild="html"
     )
-    app.add_config_value("voici_button_text", "Open with Voici", rebuild="html")
 
     # Initialize NotebookLite and JupyterLite directives
     app.add_node(
@@ -968,7 +1054,7 @@ def setup(app):
         )
     app.add_directive("jupyterlite", JupyterLiteDirective)
 
-    # Initialize Replite directive
+    # Initialize Replite directive and tab
     app.add_node(
         RepliteIframe,
         html=(visit_element_html, None),
@@ -977,6 +1063,14 @@ def setup(app):
         text=(skip, None),
         man=(skip, None),
     )
+    app.add_node(
+        RepliteTab,
+        html=(visit_element_html, None),
+        latex=(skip, None),
+        textinfo=(skip, None),
+        text=(skip, None),
+        man=(skip, None),
+    )
     app.add_directive("replite", RepliteDirective)
 
     # Initialize Voici directive and tabbed interface