Add Voici directive (#100)

* Add Voici directive

* Linter

* Add directive

* Install voici in dev env

* Update docs

* Fix iframe path

* Run black

* Missing return statement

* Try forcing building voici

* Be more clever choosing which app to build

* Fix notebook path for voici

* Linter + syntax issue

* Fix variable shadowing

* Allow for tree

* Add tree example in docs

Author: martinRenou

dev-environment.yml

@@ -14,3 +14,4 @@ dependencies:
     - black
     - pip:
         - .
+        - voici

docs/directives/voici.md

@@ -0,0 +1,29 @@
+# Voici directive
+
+`jupyterlite-sphinx` provides a `voici` directive that allows you to embed a [voici dashboard](https://github.com/voila-dashboards/voici) in your docs.
+
+```rst
+.. voici::
+   :height: 600px
+```
+
+```{eval-rst}
+.. voici::
+   :height: 600px
+```
+
+You can provide a notebook that will be rendered with Voici:
+
+```rst
+.. voici:: my_notebook.ipynb
+   :height: 600px
+   :prompt: Try Voici!
+   :prompt_color: #dc3545
+```
+
+```{eval-rst}
+.. voici:: my_notebook.ipynb
+   :height: 600px
+   :prompt: Try Voici!
+   :prompt_color: #dc3545
+```

docs/index.md

@@ -39,6 +39,7 @@ Each of those directives can be configured with the following options:
 directives/jupyterlite
 directives/retrolite
 directives/replite
+directives/voici
 full
 changelog
 ```

jupyterlite_sphinx/jupyterlite_sphinx.py

@@ -23,6 +23,8 @@
 
 CONTENT_DIR = "_contents"
 JUPYTERLITE_DIR = "lite"
+# Using a global variable, is there a better way?
+APPS = []
 
 
 # Used for nodes that do not need to be rendered
@@ -36,52 +38,29 @@ def visit_element_html(self, node):
     raise SkipNode
 
 
-class _LiteIframe(Element):
+class _PromptedIframe(Element):
     def __init__(
         self,
         rawsource="",
         *children,
-        prefix=JUPYTERLITE_DIR,
+        iframe_src="",
         width="100%",
         height="100%",
         prompt=False,
         prompt_color=None,
-        content=[],
-        notebook=None,
-        lite_options={},
         **attributes,
     ):
         super().__init__(
             "",
-            prefix=prefix,
+            iframe_src=iframe_src,
             width=width,
             height=height,
             prompt=prompt,
             prompt_color=prompt_color,
-            content=content,
-            notebook=notebook,
-            lite_options=lite_options,
         )
 
     def html(self):
-        lite_options = self["lite_options"]
-
-        if self["content"]:
-            code_lines = ["" if not line.strip() else line for line in self["content"]]
-            code = "\n".join(code_lines)
-
-            lite_options["code"] = code
-
-        app_path = self.lite_app
-        if self["notebook"] is not None:
-            lite_options["path"] = self["notebook"]
-            app_path = f"{self.lite_app}{self.notebooks_path}"
-
-        options = "&".join(
-            [f"{key}={quote(value)}" for key, value in lite_options.items()]
-        )
-
-        iframe_src = f'{self["prefix"]}/{app_path}{f"?{options}" if options else ""}'
+        iframe_src = self["iframe_src"]
 
         if self["prompt"]:
             prompt = (
@@ -108,6 +87,37 @@ def html(self):
         )
 
 
+class _LiteIframe(_PromptedIframe):
+    def __init__(
+        self,
+        rawsource="",
+        *children,
+        prefix=JUPYTERLITE_DIR,
+        content=[],
+        notebook=None,
+        lite_options={},
+        **attributes,
+    ):
+        if content:
+            code_lines = ["" 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()]
+        )
+
+        iframe_src = f'{prefix}/{app_path}{f"?{options}" if options else ""}'
+
+        super().__init__(rawsource, *children, iframe_src=iframe_src, **attributes)
+
+
 class RepliteIframe(_LiteIframe):
     """Appended to the doctree by the RepliteDirective directive
 
@@ -138,6 +148,35 @@ class RetroLiteIframe(_LiteIframe):
     notebooks_path = "notebooks/"
 
 
+class VoiciIframe(_PromptedIframe):
+    """Appended to the doctree by the VoiciDirective directive
+
+    Renders an iframe that shows a Notebook with Voici.
+    """
+
+    def __init__(
+        self,
+        rawsource="",
+        *children,
+        prefix=JUPYTERLITE_DIR,
+        notebook=None,
+        lite_options={},
+        **attributes,
+    ):
+        if notebook is not None:
+            app_path = f"voici/render/{notebook.replace('.ipynb', '.html')}"
+        else:
+            app_path = "voici/tree"
+
+        options = "&".join(
+            [f"{key}={quote(value)}" for key, value in lite_options.items()]
+        )
+
+        iframe_src = f'{prefix}/{app_path}{f"?{options}" if options else ""}'
+
+        super().__init__(rawsource, *children, iframe_src=iframe_src, **attributes)
+
+
 class RepliteDirective(SphinxDirective):
     """The ``.. replite::`` directive.
 
@@ -157,6 +196,9 @@ class RepliteDirective(SphinxDirective):
     }
 
     def run(self):
+        if not "repl" in APPS:
+            APPS.append("repl")
+
         width = self.options.pop("width", "100%")
         height = self.options.pop("height", "100%")
 
@@ -247,6 +289,12 @@ class JupyterLiteDirective(_LiteDirective):
 
     iframe_cls = JupyterLiteIframe
 
+    def run(self):
+        if not "lab" in APPS:
+            APPS.append("lab")
+
+        return super().run()
+
 
 class RetroLiteDirective(_LiteDirective):
     """The ``.. retrolite::`` directive.
@@ -256,6 +304,34 @@ class RetroLiteDirective(_LiteDirective):
 
     iframe_cls = RetroLiteIframe
 
+    def run(self):
+        if not "retro" in APPS:
+            APPS.append("retro")
+
+        return super().run()
+
+
+class VoiciDirective(_LiteDirective):
+    """The ``.. voici::`` directive.
+
+    Renders a Notebook with Voici in the docs.
+    """
+
+    iframe_cls = VoiciIframe
+
+    def run(self):
+        try:
+            import voici
+        except ImportError:
+            raise RuntimeError(
+                "Voici must be installed if you want to make use of the voici directive: pip install voici"
+            )
+
+        if not "voici" in APPS:
+            APPS.append("voici")
+
+        return super().run()
+
 
 class RetroLiteParser(RSTParser):
     """Sphinx source parser for Jupyter notebooks.
@@ -317,12 +393,17 @@ def jupyterlite_build(app: Sphinx, error):
         for content in jupyterlite_contents:
             contents.extend(["--contents", content])
 
+        apps = []
+        for jlite_app in APPS:
+            apps.extend(["--apps", jlite_app])
+
         command = [
             "jupyter",
             "lite",
             "build",
             "--debug",
             *config,
+            *apps,
             *contents,
             "--contents",
             os.path.join(app.srcdir, CONTENT_DIR),
@@ -389,6 +470,17 @@ def setup(app):
     )
     app.add_directive("replite", RepliteDirective)
 
+    # Initialize Voici directive
+    app.add_node(
+        VoiciIframe,
+        html=(visit_element_html, None),
+        latex=(skip, None),
+        textinfo=(skip, None),
+        text=(skip, None),
+        man=(skip, None),
+    )
+    app.add_directive("voici", VoiciDirective)
+
     # CSS and JS assets
     copy_asset(str(HERE / "jupyterlite_sphinx.css"), str(Path(app.outdir) / "_static"))
     copy_asset(str(HERE / "jupyterlite_sphinx.js"), str(Path(app.outdir) / "_static"))