Merge pull request #223 from agriyakhetarpal/feat/new-tabs-for-notebooklite-directive

Add an option to open the Notebook UI and Voici apps in a new tab via the`NotebookLite` and `Voici` directives

Author: agriyakhetarpal

docs/directives/jupyterlite.md

@@ -37,6 +37,8 @@ You can also pass a Notebook file to open automatically:
 ```
 
 If you use the `:new_tab:` option in the directive, the Notebook will be opened in a new browser tab.
+The tab will render the full-fledged Lab interface, which is more complete and showcases all features
+of JupyterLite.
 
 ```rst
 .. jupyterlite:: my_notebook.ipynb

docs/directives/notebooklite.md

@@ -31,3 +31,17 @@ You can also pass a Notebook file to open:
    :height: 600px
    :prompt: Try classic Notebook!
 ```
+
+If you use the `:new_tab:` option in the directive, the Notebook will be opened in a new browser tab.
+The tab will render the classic Notebook UI, which is more minimal and does not showcase the entire
+Lab interface.
+
+```rst
+.. notebooklite:: my_notebook.ipynb
+   :new_tab: True
+```
+
+```{eval-rst}
+.. notebooklite:: my_notebook.ipynb
+   :new_tab: True
+```

docs/directives/voici.md

@@ -27,3 +27,17 @@ You can provide a notebook that will be rendered with Voici:
    :prompt: Try Voici!
    :prompt_color: #dc3545
 ```
+
+If you use the `:new_tab:` option in the directive, the Voici dashboard will execute and render
+the notebook in a new browser tab, instead of in the current page.
+
+```rst
+.. voici:: my_notebook.ipynb
+   :new_tab: True
+```
+
+```{eval-rst}
+.. voici:: my_notebook.ipynb
+   :new_tab: True
+```
+

jupyterlite_sphinx/jupyterlite_sphinx.py

@@ -204,7 +204,15 @@ class JupyterLiteIframe(_LiteIframe):
     notebooks_path = ""
 
 
-class JupyterLiteTab(_InTab):
+class BaseNotebookTab(_InTab):
+    """Base class for notebook tab implementations. We subclass this
+    to create more specific configurations around how tabs are rendered."""
+
+    lite_app = None
+    notebooks_path = None
+
+
+class JupyterLiteTab(BaseNotebookTab):
     """Appended to the doctree by the JupyterliteDirective directive
 
     Renders a button that opens a Notebook with JupyterLite in a new tab.
@@ -214,6 +222,16 @@ class JupyterLiteTab(_InTab):
     notebooks_path = ""
 
 
+class NotebookLiteTab(BaseNotebookTab):
+    """Appended to the doctree by the NotebookliteDirective directive
+
+    Renders a button that opens a Notebook with NotebookLite in a new tab.
+    """
+
+    lite_app = "tree/"
+    notebooks_path = "../notebooks/"
+
+
 class NotebookLiteIframe(_LiteIframe):
     """Appended to the doctree by the NotebookliteDirective directive
 
@@ -224,6 +242,21 @@ class NotebookLiteIframe(_LiteIframe):
     notebooks_path = "../notebooks/"
 
 
+class VoiciBase:
+    """Base class with common Voici application paths and URL structure"""
+
+    lite_app = "voici/"
+
+    @classmethod
+    def get_full_path(cls, notebook=None):
+        """Get the complete Voici path based on whether a notebook is provided."""
+        if notebook is not None:
+            # For notebooks, use render path with html extension
+            return f"{cls.lite_app}render/{notebook.replace('.ipynb', '.html')}"
+        # Default to tree view
+        return f"{cls.lite_app}tree"
+
+
 class VoiciIframe(_PromptedIframe):
     """Appended to the doctree by the VoiciDirective directive
 
@@ -239,20 +272,55 @@ def __init__(
         lite_options={},
         **attributes,
     ):
-        if notebook is not None:
-            app_path = f"voici/render/{notebook.replace('.ipynb', '.html')}"
-        else:
-            app_path = "voici/tree"
-
+        app_path = VoiciBase.get_full_path(notebook)
         options = "&".join(
             [f"{key}={quote(value)}" for key, value in lite_options.items()]
         )
 
+        # If a notebook is provided, open it in the render view. Else, we default to the tree view.
         iframe_src = f'{prefix}/{app_path}{f"index.html?{options}" if options else ""}'
 
         super().__init__(rawsource, *children, iframe_src=iframe_src, **attributes)
 
 
+# We do not inherit from BaseNotebookTab here because
+# Voici has a different URL structure.
+class VoiciTab(Element):
+    """Tabbed implementation for the Voici interface"""
+
+    def __init__(
+        self,
+        rawsource="",
+        *children,
+        prefix=JUPYTERLITE_DIR,
+        notebook=None,
+        lite_options={},
+        **attributes,
+    ):
+
+        self.lab_src = f"{prefix}/"
+
+        app_path = VoiciBase.get_full_path(notebook)
+        options = "&".join(
+            [f"{key}={quote(value)}" for key, value in lite_options.items()]
+        )
+
+        # If a notebook is provided, open it in a new tab. Else, we default to the tree view.
+        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 with Voici</button>"
+        )
+
+
 class RepliteDirective(SphinxDirective):
     """The ``.. replite::`` directive.
 
@@ -400,7 +468,24 @@ def run(self):
         ]
 
 
-class JupyterLiteDirective(_LiteDirective):
+class BaseJupyterViewDirective(_LiteDirective):
+    """Base class for jupyterlite-sphinx directives."""
+
+    iframe_cls = None  # to be defined by subclasses
+    newtab_cls = None  # to be defined by subclasses
+
+    option_spec = {
+        "width": directives.unchanged,
+        "height": directives.unchanged,
+        "theme": directives.unchanged,
+        "prompt": directives.unchanged,
+        "prompt_color": directives.unchanged,
+        "search_params": directives.unchanged,
+        "new_tab": directives.unchanged,
+    }
+
+
+class JupyterLiteDirective(BaseJupyterViewDirective):
     """The ``.. jupyterlite::`` directive.
 
     Renders a Notebook with JupyterLite in the docs.
@@ -410,22 +495,24 @@ class JupyterLiteDirective(_LiteDirective):
     newtab_cls = JupyterLiteTab
 
 
-class NotebookLiteDirective(_LiteDirective):
+class NotebookLiteDirective(BaseJupyterViewDirective):
     """The ``.. notebooklite::`` directive.
 
     Renders a Notebook with NotebookLite in the docs.
     """
 
     iframe_cls = NotebookLiteIframe
+    newtab_cls = NotebookLiteTab
 
 
-class VoiciDirective(_LiteDirective):
+class VoiciDirective(BaseJupyterViewDirective):
     """The ``.. voici::`` directive.
 
     Renders a Notebook with Voici in the docs.
     """
 
     iframe_cls = VoiciIframe
+    newtab_cls = VoiciTab
 
     def run(self):
         if voici is None:
@@ -810,30 +897,39 @@ def setup(app):
         text=(skip, None),
         man=(skip, None),
     )
+    for node_class in [NotebookLiteTab, JupyterLiteTab]:
+        app.add_node(
+            node_class,
+            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
     app.add_node(
-        JupyterLiteTab,
+        RepliteIframe,
         html=(visit_element_html, None),
         latex=(skip, None),
         textinfo=(skip, None),
         text=(skip, None),
         man=(skip, None),
     )
-    app.add_directive("jupyterlite", JupyterLiteDirective)
+    app.add_directive("replite", RepliteDirective)
 
-    # Initialize Replite directive
+    # Initialize Voici directive and tabbed interface
     app.add_node(
-        RepliteIframe,
+        VoiciIframe,
         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
     app.add_node(
-        VoiciIframe,
+        VoiciTab,
         html=(visit_element_html, None),
         latex=(skip, None),
         textinfo=(skip, None),