Merge pull request #165 from melissawm/add-tab

Add the option to open JupyterLite window in new tab

Author: Carreau

docs/directives/jupyterlite.md

@@ -36,6 +36,18 @@ You can also pass a Notebook file to open automatically:
    :prompt_color: #00aa42
 ```
 
+If you use the `:new_tab:` option in the directive, the Notebook will be opened in a new browser tab.
+
+```rst
+.. jupyterlite:: my_notebook.ipynb
+   :new_tab: True
+```
+
+```{eval-rst}
+.. jupyterlite:: my_notebook.ipynb
+   :new_tab: True
+```
+
 The directive `search_params` allows to transfer some search parameters from the documentation URL to the Jupyterlite URL.\
 Jupyterlite will then be able to fetch these parameters from its own URL.\
 For example `:search_params: ["param1", "param2"]` will transfer the parameters *param1* and *param2*.

jupyterlite_sphinx/jupyterlite_sphinx.py

@@ -109,6 +109,39 @@ def html(self):
         )
 
 
+class _InTab(Element):
+    def __init__(
+        self,
+        rawsource="",
+        *children,
+        prefix=JUPYTERLITE_DIR,
+        notebook=None,
+        lite_options={},
+        **attributes,
+    ):
+        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"?{options}" if options else ""}'
+
+        super().__init__(
+            rawsource,
+            **attributes,
+        )
+
+    def html(self):
+        return (
+            '<button class="try_examples_button" '
+            f"onclick=\"window.open('{self.lab_src}')\">"
+            "Open as a notebook</button>"
+        )
+
+
 class _LiteIframe(_PromptedIframe):
     def __init__(
         self,
@@ -167,6 +200,16 @@ class JupyterLiteIframe(_LiteIframe):
     notebooks_path = ""
 
 
+class JupyterLiteTab(_InTab):
+    """Appended to the doctree by the JupyterliteDirective directive
+
+    Renders a button that opens a Notebook with JupyterLite in a new tab.
+    """
+
+    lite_app = "lab/"
+    notebooks_path = ""
+
+
 class NotebookLiteIframe(_LiteIframe):
     """Appended to the doctree by the NotebookliteDirective directive
 
@@ -264,6 +307,7 @@ class _LiteDirective(SphinxDirective):
         "prompt": directives.unchanged,
         "prompt_color": directives.unchanged,
         "search_params": directives.unchanged,
+        "new_tab": directives.unchanged,
     }
 
     def run(self):
@@ -275,6 +319,8 @@ def run(self):
 
         search_params = search_params_parser(self.options.pop("search_params", False))
 
+        new_tab = self.options.pop("new_tab", False)
+
         source_location = os.path.dirname(self.get_source_info()[0])
 
         prefix = os.path.relpath(
@@ -301,6 +347,20 @@ def run(self):
         else:
             notebook_name = None
 
+        if new_tab:
+            return [
+                self.newtab_cls(
+                    prefix=prefix,
+                    notebook=notebook_name,
+                    width=width,
+                    height=height,
+                    prompt=prompt,
+                    prompt_color=prompt_color,
+                    search_params=search_params,
+                    lite_options=self.options,
+                )
+            ]
+
         return [
             self.iframe_cls(
                 prefix=prefix,
@@ -322,6 +382,7 @@ class JupyterLiteDirective(_LiteDirective):
     """
 
     iframe_cls = JupyterLiteIframe
+    newtab_cls = JupyterLiteTab
 
 
 class NotebookLiteDirective(_LiteDirective):
@@ -721,6 +782,14 @@ def setup(app):
         text=(skip, None),
         man=(skip, None),
     )
+    app.add_node(
+        JupyterLiteTab,
+        html=(visit_element_html, None),
+        latex=(skip, None),
+        textinfo=(skip, None),
+        text=(skip, None),
+        man=(skip, None),
+    )
     app.add_directive("jupyterlite", JupyterLiteDirective)
 
     # Initialize Replite directive