Merge pull request #19 from martinRenou/add_jupyterlite_directive

Add jupyterlite directive and rework docs

Author: martinRenou

docs/configuration.rst

@@ -0,0 +1,35 @@
+Configuration
+=============
+
+You can provide custom configuration to your JupyterLite deployment.
+
+For example, if you want to have bqplot working in this deployment, you need to install the bqplot federated extension
+and you can serve the bqplot wheel to ``piplite``, this is done by telling your ``conf.py`` where to look for the jupyterlite config:
+
+.. code-block:: python
+
+    jupyterlite_config = "jupyterlite_config.json"
+
+The ``jupyterlite_config.json`` containing the following:
+
+.. code-block:: json
+
+    {
+        "LiteBuildConfig": {
+            "federated_extensions": [
+                "https://github.com/conda-forge/releases/releases/download/noarch/bqplot-0.12.33-pyhd8ed1ab_0.tar.bz2/bqplot-0.12.33-pyhd8ed1ab_0.tar.bz2",
+            ],
+            "ignore_sys_prefix": true,
+            "piplite_urls": [
+                "https://files.pythonhosted.org/packages/py2.py3/b/bqplot/bqplot-0.12.33-py2.py3-none-any.whl",
+            ]
+        }
+    }
+
+Then you should be able to show Notebooks working with bqplot!
+
+.. code-block:: rst
+
+    .. retrolite:: bqplot.ipynb
+
+.. retrolite:: bqplot.ipynb

docs/index.rst

@@ -1,121 +1,27 @@
 jupyterlite-sphinx
 ==================
 
-Installation
-------------
-
-You can install ``jupyterlite-sphinx`` with ``pip``:
-
-.. code-block::
-
-    pip install jupyterlite-sphinx
-
-then you need to add the ``jupyterlite-sphinx`` extension to your ``conf.py`` file of your sphinx docs:
-
-.. code-block:: python
-
-    extensions = [
-        'jupyterlite_sphinx',
-        # And other sphinx extensions
-        # ...
-    ]
-
-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.
-
-.. code-block:: rst
-
-    .. replite::
-       :kernel: python
-       :toolbar: 1
-       :theme: JupyterLab Light
-       :width: 100%
-       :height: 600px
-
-        print('Hello, World!')
-
-.. replite::
-   :kernel: python
-   :toolbar: 1
-   :theme: JupyterLab Light
-   :width: 100%
-   :height: 600px
-
-    print('Hello, World!')
-
-Retrolite directive
--------------------
-
-``jupyterlite-sphinx`` provides a ``retrolite`` directive that allows you to embed an entire executable Notebook in your docs.
-It takes the name of the Notebook as argument:
-
-.. code-block:: rst
-
-    .. retrolite:: my_notebook.ipynb
-       :width: 100%
-       :height: 600px
-
-.. retrolite:: my_notebook.ipynb
-   :width: 100%
-   :height: 600px
-
-Or you can simply show the filetree:
-
-.. code-block:: rst
-
-    .. retrolite::
-       :width: 100%
-       :height: 600px
-
-.. retrolite::
-   :width: 100%
-   :height: 600px
-
-
-JupyterLab and RetroLab deployed for you
-----------------------------------------
+A Sphinx extension that provides utilities for embedding JupyterLite in your docs.
 
 ``jupyterlite-sphinx`` makes a full deployment of JupyterLite for you, you can access the JupyterLab UI and RetroLab UI following the
 ``./lite/lab/index.html`` and ``./lite/retro/index.html`` relative URLs:
 
 `JupyterLab <./lite/lab/index.html>`_
-`Retrolab <./lite/retro/index.html>`_
-
-Configuration
--------------
-
-You can provide custom configuration to your JupyterLite deployment.
-
-For example, if you want to have bqplot working in this deployment, you need to install the bqplot federated extension
-and you can serve the bqplot wheel to ``piplite``, this is done by telling your ``conf.py`` where to look for the jupyterlite config:
 
-.. code-block:: python
-
-    jupyterlite_config = "jupyterlite_config.json"
-
-The ``jupyterlite_config.json`` containing the following:
-
-.. code-block:: json
+`Retrolab <./lite/retro/index.html>`_
 
-    {
-        "LiteBuildConfig": {
-            "federated_extensions": [
-                "https://github.com/conda-forge/releases/releases/download/noarch/bqplot-0.12.33-pyhd8ed1ab_0.tar.bz2/bqplot-0.12.33-pyhd8ed1ab_0.tar.bz2",
-            ],
-            "ignore_sys_prefix": true,
-            "piplite_urls": [
-                "https://files.pythonhosted.org/packages/py2.py3/b/bqplot/bqplot-0.12.33-py2.py3-none-any.whl",
-            ]
-        }
-    }
 
-Then you should be able to show Notebooks working with bqplot!
+.. toctree::
+    :caption: Installation
+    :maxdepth: 2
 
-.. code-block:: rst
+    installation
+    configuration
 
-    .. retrolite:: bqplot.ipynb
+.. toctree::
+    :caption: Usage
+    :maxdepth: 2
 
-.. retrolite:: bqplot.ipynb
+    jupyterlite
+    retrolite
+    replite

docs/installation.rst

@@ -0,0 +1,18 @@
+Installation
+============
+
+You can install ``jupyterlite-sphinx`` with ``pip``:
+
+.. code-block::
+
+    pip install jupyterlite-sphinx
+
+then you need to add the ``jupyterlite-sphinx`` extension to your ``conf.py`` file of your sphinx docs:
+
+.. code-block:: python
+
+    extensions = [
+        'jupyterlite_sphinx',
+        # And other sphinx extensions
+        # ...
+    ]

docs/jupyterlite.rst

@@ -0,0 +1,26 @@
+JupyterLite directive
+=====================
+
+``jupyterlite-sphinx`` provides a ``jupyterlite`` directive that allows you to embed JupyterLab in your docs.
+
+.. code-block:: rst
+
+    .. jupyterlite::
+       :width: 100%
+       :height: 600px
+
+.. jupyterlite::
+   :width: 100%
+   :height: 600px
+
+You can also pass a Notebook file to open automatically:
+
+.. code-block:: rst
+
+    .. jupyterlite:: my_notebook.ipynb
+       :width: 100%
+       :height: 600px
+
+.. jupyterlite:: my_notebook.ipynb
+   :width: 100%
+   :height: 600px

docs/replite.rst

@@ -0,0 +1,25 @@
+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.
+
+.. code-block:: rst
+
+    .. replite::
+       :kernel: python
+       :toolbar: 1
+       :theme: JupyterLab Light
+       :width: 100%
+       :height: 600px
+
+        print('Hello, World!')
+
+.. replite::
+   :kernel: python
+   :toolbar: 1
+   :theme: JupyterLab Light
+   :width: 100%
+   :height: 600px
+
+    print('Hello, World!')

docs/retrolite.rst

@@ -0,0 +1,26 @@
+RetroLite directive
+===================
+
+``jupyterlite-sphinx`` provides a ``retrolite`` directive that allows you to embed Retrolab in your docs.
+
+.. code-block:: rst
+
+    .. retrolite::
+       :width: 100%
+       :height: 600px
+
+.. retrolite::
+   :width: 100%
+   :height: 600px
+
+You can also pass a Notebook file to open:
+
+.. code-block:: rst
+
+    .. retrolite:: my_notebook.ipynb
+       :width: 100%
+       :height: 600px
+
+.. retrolite:: my_notebook.ipynb
+   :width: 100%
+   :height: 600px

src/jupyterlite_sphinx.py

@@ -86,12 +86,7 @@ def run(self):
         return [RepliteIframe(width=width, height=height, replite_options=self.options)]
 
 
-class RetroliteIframe(Element):
-    """Appended to the doctree by the RetroliteDirective directive
-
-    Renders an iframe that shows a Notebook with RetroLite.
-    """
-
+class _LiteIframe(Element):
     def __init__(
         self,
         rawsource="",
@@ -107,9 +102,9 @@ def html(self):
         notebook = self["notebook"]
 
         src = (
-            f"{JUPYTERLITE_DIR}/retro/notebooks/?path={notebook}"
+            f"{JUPYTERLITE_DIR}/{self.lite_app}/{self.notebooks_path}?path={notebook}"
             if notebook is not None
-            else f"{JUPYTERLITE_DIR}/retro"
+            else f"{JUPYTERLITE_DIR}/{self.lite_app}"
         )
 
         return (
@@ -118,12 +113,28 @@ def html(self):
         )
 
 
-class RetroliteDirective(SphinxDirective):
-    """The ``.. retrolite::`` directive.
+class JupyterLiteIframe(_LiteIframe):
+    """Appended to the doctree by the JupyterliteDirective directive
 
-    Renders a Notebook with RetroLite in the docs.
+    Renders an iframe that shows a Notebook with JupyterLite.
+    """
+
+    lite_app = "lab"
+    notebooks_path = ""
+
+
+class RetroLiteIframe(_LiteIframe):
+    """Appended to the doctree by the RetroliteDirective directive
+
+    Renders an iframe that shows a Notebook with RetroLite.
     """
 
+    lite_app = "retro"
+    notebooks_path = "notebooks/"
+
+
+class _LiteDirective(SphinxDirective):
+
     has_content = False
     optional_arguments = 1
     option_spec = {
@@ -154,7 +165,25 @@ def run(self):
         else:
             notebook_name = None
 
-        return [RetroliteIframe(notebook=notebook_name, width=width, height=height)]
+        return [self.iframe_cls(notebook=notebook_name, width=width, height=height)]
+
+
+class JupyterLiteDirective(_LiteDirective):
+    """The ``.. jupyterlite::`` directive.
+
+    Renders a Notebook with JupyterLite in the docs.
+    """
+
+    iframe_cls = JupyterLiteIframe
+
+
+class RetroLiteDirective(_LiteDirective):
+    """The ``.. retrolite::`` directive.
+
+    Renders a Notebook with RetroLite in the docs.
+    """
+
+    iframe_cls = RetroLiteIframe
 
 
 class RetroLiteParser(rst.Parser):
@@ -213,25 +242,34 @@ def jupyterlite_build(app: Sphinx, error):
 
 
 def setup(app):
-    # Build the JupyterLite output
     app.connect("config-inited", inited)
     # We need to build JupyterLite at the end, when all the content was created
     app.connect("build-finished", jupyterlite_build)
 
     # Config options
     app.add_config_value("jupyterlite_config", None, rebuild="html")
 
-    # Initialize RetroLite directive and parser
+    # Initialize RetroLite and JupyterLite directives
+    app.add_node(
+        RetroLiteIframe,
+        html=(visit_element_html, None),
+        latex=(skip, None),
+        textinfo=(skip, None),
+        text=(skip, None),
+        man=(skip, None),
+    )
+    app.add_directive("retrolite", RetroLiteDirective)
     app.add_node(
-        RetroliteIframe,
+        JupyterLiteIframe,
         html=(visit_element_html, None),
         latex=(skip, None),
         textinfo=(skip, None),
         text=(skip, None),
         man=(skip, None),
     )
-    app.add_directive("retrolite", RetroliteDirective)
+    app.add_directive("jupyterlite", JupyterLiteDirective)
 
+    # Initialize RetroLite parser
     app.add_source_parser(RetroLiteParser)
     app.add_source_suffix(".ipynb", "jupyterlite_notebook")