Feature: optional prompt button for lazy loading the JupyterLite UI

Author: martinRenou

.github/workflows/main.yml

@@ -37,4 +37,4 @@ jobs:
         channels: conda-forge
 
     - name: Test PEP8
-      run: black --check src
+      run: black --check jupyterlite_sphinx

.gitignore

@@ -1,4 +1,4 @@
-src/jupyterlite_sphinx.egg-info
+jupyterlite_sphinx/jupyterlite_sphinx.egg-info
 **/.ipynb_checkpoints
 **/__pycache__
 docs/build

MANIFEST.in

@@ -0,0 +1,13 @@
+include LICENSE
+include README.md
+include setup.py
+
+graft jupyterlite_sphinx
+graft docs
+
+# Patterns to exclude from any directory
+global-exclude *~
+global-exclude *.pyc
+global-exclude *.pyo
+global-exclude .git
+global-exclude .ipynb_checkpoints

docs/conf.py

@@ -9,6 +9,7 @@
 
 jupyter_lite_config = "jupyter_lite_config.json"
 jupyter_lite_contents = "./custom_contents"
+jupyterlite_bind_ipynb_suffix = False
 
 master_doc = 'index'
 

docs/directives/jupyterlite.rst

@@ -8,10 +8,14 @@ JupyterLite directive
     .. jupyterlite::
        :width: 100%
        :height: 600px
+       :prompt: Try JupyterLite!
+       :prompt_color: #00aa42
 
 .. jupyterlite::
    :width: 100%
    :height: 600px
+   :prompt: Try JupyterLite!
+   :prompt_color: #00aa42
 
 You can also pass a Notebook file to open automatically:
 
@@ -20,7 +24,11 @@ You can also pass a Notebook file to open automatically:
     .. jupyterlite:: my_notebook.ipynb
        :width: 100%
        :height: 600px
+       :prompt: Try JupyterLite!
+       :prompt_color: #00aa42
 
 .. jupyterlite:: my_notebook.ipynb
    :width: 100%
    :height: 600px
+   :prompt: Try JupyterLite!
+   :prompt_color: #00aa42

docs/directives/replite.rst

@@ -2,13 +2,15 @@ Replite directive
 =================
 
 ``jupyterlite-sphinx`` provides a ``replite`` directive that allows you to embed a replite console in your docs.
-This directive takes the same options as the ``replite`` package, see https://github.com/jtpio/replite for reference.
+This directive takes extra options which are the same options as the ``replite`` package, see https://github.com/jtpio/replite for reference.
 
 .. code-block:: rst
 
    .. replite::
       :kernel: python
       :height: 600px
+      :prompt: Try Replite!
+      :prompt_color: #dc3545
 
       import matplotlib.pyplot as plt
       import numpy as np
@@ -23,6 +25,8 @@ This directive takes the same options as the ``replite`` package, see https://gi
 .. replite::
    :kernel: python
    :height: 600px
+   :prompt: Try Replite!
+   :prompt_color: #dc3545
 
    import matplotlib.pyplot as plt
    import numpy as np

docs/directives/retrolite.rst

@@ -8,10 +8,12 @@ RetroLite directive
     .. retrolite::
        :width: 100%
        :height: 600px
+       :prompt: Try Retrolite!
 
 .. retrolite::
    :width: 100%
    :height: 600px
+   :prompt: Try Retrolite!
 
 You can also pass a Notebook file to open:
 
@@ -20,7 +22,9 @@ You can also pass a Notebook file to open:
     .. retrolite:: my_notebook.ipynb
        :width: 100%
        :height: 600px
+       :prompt: Try Retrolite!
 
 .. retrolite:: my_notebook.ipynb
    :width: 100%
    :height: 600px
+   :prompt: Try Retrolite!

docs/index.rst

@@ -15,14 +15,24 @@ A Sphinx extension that provides utilities for embedding JupyterLite in your doc
    print("Hello from a JupyterLite console!")
 
 .. toctree::
-    :caption: Installation
     :maxdepth: 2
 
     installation
     configuration
 
+Usage
+-----
+
+``jupyterlite-sphinx`` provides a collection of directives that allows you to embed the different JupyterLite UIs directly in your documentation page.
+Each of those directives can be configured with the following options:
+
+- ``width`` (default ``"100%"``) the width of the UI
+- ``height`` (default ``"600px"``) the height of the UI
+- ``theme`` (default ``None``) the JupyterLab theme to use
+- ``prompt`` (default ``False``) whether or not to lazy-load the UI. If the value is a string, it will use this value for the prompt button.
+- ``prompt_color`` (default ``#f7dc1e``) The color of the prompt button, if there is one.
+
 .. toctree::
-    :caption: Usage
     :maxdepth: 2
 
     directives/jupyterlite

jupyterlite_sphinx/__init__.py

@@ -0,0 +1 @@
+from .jupyterlite_sphinx import setup  ## noqa

jupyterlite_sphinx/jupyterlite_sphinx.css

@@ -0,0 +1,69 @@
+.jupyterlite_sphinx_raw_iframe {
+    border-width: 1px;
+    border-style: solid;
+    border-color: #d8d8d8;
+    box-shadow: 0 0.2rem 0.5rem #d8d8d8;
+}
+
+.jupyterlite_sphinx_iframe_container {
+    border-width: 1px;
+    border-style: solid;
+    border-color: #d8d8d8;
+    position: relative;
+    cursor: pointer;
+    box-shadow: 0 0.2rem 0.5rem #d8d8d8;
+}
+
+.jupyterlite_sphinx_iframe {
+    z-index: 1;
+    position: relative;
+    border-style: none;
+}
+
+.jupyterlite_sphinx_try_it_button {
+    z-index: 0;
+    position: absolute;
+    left: 50%;
+    top: 50%;
+    transform: translateY(-50%) translateX(-50%);
+    height: 100px;
+    width: 100px;
+    line-height: 100px;
+    text-align: center;
+    white-space: nowrap;
+    background-color: #f7dc1e;
+    border-radius: 50%;
+    font-family: vibur;
+    font-size: larger;
+    box-shadow: 0 0.2rem 0.5rem #d8d8d8;
+}
+
+.jupyterlite_sphinx_iframe_container:hover .jupyterlite_sphinx_try_it_button_unclicked {
+    -webkit-animation:grow 0.2s ease-in-out;
+    animation:grow 0.2s ease-in-out;
+    transform: translateY(-50%) translateX(-50%) scale(1.2);
+}
+
+.jupyterlite_sphinx_try_it_button_clicked {
+    -webkit-animation:grow 1s infinite alternate;
+    animation:grow 1s infinite alternate;
+    transform: translateY(-50%) translateX(-50%) scale(1.2);
+}
+
+@keyframes grow {
+    from {
+        transform: translateY(-50%) translateX(-50%) scale(1);
+    }
+    to {
+        transform: translateY(-50%) translateX(-50%) scale(1.2);
+    }
+}
+
+@-webkit-keyframes grow {
+    from {
+        transform: translateY(-50%) translateX(-50%) scale(1);
+    }
+    to {
+        transform: translateY(-50%) translateX(-50%) scale(1.2);
+    }
+}