Update Documentation (#333)

* fix: storybook * storybook: favot micropip * storybook: lexical * Automatic application of license header * chore: kernel indicator * example: add indicator to notebook lite * docs: fix * chore: make @jupyterlite/pyodide-kernel-extension a dependency * chore: make @jupyterlite/pyodide-kernel-extension a dependency * examples: config * docs: review * toc: docs * docs: lint * Automatic application of license header --------- Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
datalayer · Dec 5, 2024 · dc27295 · dc27295
1 parent 7588586
commit dc27295
Show file tree

Hide file tree

Showing 116 changed files with 817 additions and 739 deletions.
diff --git a/docs/docs/about/index.mdx b/docs/docs/about/index.mdx
@@ -1,56 +1,48 @@
----
-description: About Jupyter UI.
----
-
 import ModalImage from "react-modal-image";
 
 # 🪐 ⚛️ About Jupyter UI
 
-Jupyter UI is a set of [React.js](https://reactjs.org) components that allow a frontend developer to build data products compatible with the [Jupyter](https://jupyter.org) ecosystem. The user interface delivers executable notebooks, cells, terminals, file browsers and allows the developer to manage a full integrated React tree instead of relying on iframes to display the Jupyter noteboks.
+Jupyter UI is a set of [React.js](https://reactjs.org) components that allow a Web application developer to build [Data Products and Data Platforms](https://datalayer.tech/docs/glossary) compatible with the [Jupyter](https://jupyter.org) ecosystem. The user interface delivers executable notebooks, cells, terminals, file browsers and allows the developer to manage a full integrated React tree instead of relying on iframes to display the Jupyter Notebooks.
 
-The Jupyter(Lab) Notebook is a tool that allows data scientist to analyse dataset. However, it is not easy to create a custom user interface integrated in an existing application. Jupyter UI, [an open-source library](https://github.com/datalayer/jupyter-ui), fills that gap and provides components that a developer can easily integrate in any React.js application.
+Jupyter(Lab) Notebook is a tool that allows Data Scientists to analyse datasets. However, it is not easy to create a custom user interface integrated in an existing application. Jupyter UI, [an open-source library](https://github.com/datalayer/jupyter-ui), fills that gap and provides components that a developer can easily integrate in any React.js application.
 
 We ensure React.js as a first-class citizen in the Jupyter:
 
-- [Components](/docs/category/components): JupyterLab visual as React.js components
-- [Integrations](/docs/category/integrations): Embed Jupyter in Docusaurus.
-- [Themes](/docs/category/themes): Themes for your data analysis.
-
-You can get kick-started with simple [examples](/docs/category/examples)
-
-## Problems with JupyterLab for Web developers
-
-In terms of technical stack, the Jupyter(Lab) user interface is built on top of Lumino, which is an imperative way to build user interface and **can not** be consumed by industry standard declarative frameworks like React.js. As a user interface developer, if you want to create a custom data product on top of Jupyter, you have to stick to Lumino and carry-on the full notebook interface not tailored to your specific needs. This is not what you want. You just want to expose what you need, you want to develop with your favorite toolkit (like React.js) and you also want to integrate on a per-component basis the Jupyter functionality in your application.
+- [Components](/docs/components): JupyterLab visual as React.js components
+- [Integrations](/docs/integrations): Integrate Jupyter in Docusaurus, Next.js...
+- [Themes](/docs/themes): Themes for your data analysis.
 
-[JupyterLab](https://github.com/jupyterlab/jupyterlab) is built on the [Lumino](https://github.com/jupyterlab/lumino) widget toolkit.
-
-1. Lumino allows to wrap React components and expose them as Lumino Widgets.
-2. React.js **can not** use Lumino Widgets.
+## Why?
 
-:::caution
+:::info
 
 Although a developer can embed a React.js component into JupyterLab, the reverse is not possible.
 
-**You can NOT embed JupyterLab into a React.js application**.
+**You can NOT embed JupyterLab into a React.js application - This is that issue that Jupyter UI solves.**.
 
 :::
 
-## Jupyter UI at the rescue
+JupyterLab is not usagble by Web Developers. Jupyter(Lab) user interfaces are built on top of [Lumino](https://github.com/jupyterlab/lumino) widget toolkit, which is an [imperative way](https://en.wikipedia.org/wiki/Imperative_programming) to build user interface and **can not** be consumed by industry standard declarative frameworks like React.js. As a user interface developer, if you want to create a custom [Data Products and Data Platforms](https://datalayer.tech/docs/glossary) on top of Jupyter, you have to stick to Lumino and carry-on the full notebook interface not tailored to your specific needs. This is not what you want. You just want to expose what you need, you want to develop with your favorite [declarative](https://en.wikipedia.org/wiki/Declarative_programming) toolkit (like React.js) and you also want to integrate on a per-component basis the Jupyter functionality in your application.
 
-Jupyter UI provides the foundations to build a modern and flexible data prodcut user interface. Underneath, it gathers the minimum set of [Lumino](https://github.com/jupyterlab/lumino) and [JupyterLab](https://github.com/jupyterlab/jupyterlab) technologies. We wrap Lumino Widget in a React.js component and expose Redux Observables actions that proxy Lumino Commands. We bind Redux Observables Epics to Lumino Signals. Those bindings convert Lumino Signals to Observable to run the needed actions in the [Observable Epics](https://redux-observable.js.org/docs/basics/Epics.html).
+1. Lumino allows to wrap React components and expose them as Lumino Widgets.
+2. React.js **can not** use Lumino Widgets.
+
+## Jupyter UI at the Rescue
+
+Jupyter UI provides the foundations to build a modern and flexible [Data Products and Data Platforms](https://datalayer.tech/docs/glossary) user interface. Underneath, it gathers the minimum set of [Lumino](https://github.com/jupyterlab/lumino) and [JupyterLab](https://github.com/jupyterlab/jupyterlab) technologies. We wrap Lumino Widget in a React.js component and expose Zustands actions that proxy Lumino Commands. We bind Zustands Epics to Lumino Signals. Those bindings convert Lumino Signals to Observable to run the needed actions in the [Observable Epics](https://redux-observable.js.org/docs/basics/Epics.html).
 
 - Services to connect to kernels.
 - Extension injection system.
-- Lumino signals and messages integrated with Redux.
+- Lumino signals and messages integrated with Zustand.
 - Lumino commands.
 
-To solve the above issues, Jupyter UI ships components to easily create a React.js data product compatible with the Jupyter ecosystem. Those components can be used in any React.js application, and also in static websites like Docusaurus, Next.js or Remix. They wrap underneath the JupyterLab code and allow developing React.js applications with code execution capability. State management is based on Redux, and Mobx is to be added.
+To solve the above issues, Jupyter UI ships components to easily create a React.js [Data Products and Data Platforms](https://datalayer.tech/docs/glossary) compatible with the Jupyter ecosystem. Those components can be used in any React.js application, and also in static websites like Docusaurus, Next.js or Remix. They wrap underneath the JupyterLab code and allow developing React.js applications with code execution capability. State management is based on Zustand, and Mobx is to be added.
 
-The Jupyter UI components expose JupyterLab visuals as React.js components and offers a bi-directional communication between React.js/Redux and JupyterLab/Lumino.
+The Jupyter UI components expose JupyterLab visuals as React.js components and offers a bi-directional communication between React.js/Zustand and JupyterLab/Lumino.
 
 ```
-Host application -> Redux Observable Actions -> Jupyter UI -> JupyterLab Commands
-Host application <- Redux State  <- Redux Observable Epics <- Jupyter UI <- JupyterLab Signals
+Host application -> Zustand Actions -> Jupyter UI -> JupyterLab Commands
+Host application <- Redux State <- Jupyter UI <- JupyterLab Signals
 ```
 
 <ModalImage
@@ -65,31 +57,17 @@ You can find more context reading this [abstract](https://fosdem.org/2022/schedu
 
 ## Examples
 
-The below image shows a gallery of the available React.js components ready to be used in you custom application. These open source components are used to build the [online Datalayer platform](https://datalayer.io), a collaborative platform for data analysis.
+The below image shows a gallery of the available React.js components ready to be used in you custom application. These open source components are used to build the [Datalayer SaaS, a collaborative platform for data analysis](https://datalayer.io).
 
 <ModalImage
   small="https://datalayer-jupyter-examples.s3.amazonaws.com/jupyter-react-gallery.gif"
   large="https://datalayer-jupyter-examples.s3.amazonaws.com/jupyter-react-gallery.gif"
   alt="Jupyter UI Gallery"
 />
 
-## Open Source
-
-The open source components removes the above limitations and supports:
-
-- Predefined Redux actions, epics and reducers with [Observable Epics](https://redux-observable.js.org/docs/basics/Epics.html)
-- Everything is created in a single React tree to ensure Jupyter UI components can use any context created by the host application.
-- IPyWidgets and Panel interactive widgets are supported.
-- Collaborative RTC is also supported.
-- Plays nice with Jupyter Auth, Jupyterpool, Primer React, Material-UI , Storybook, Docusaurus, Emotion.js... and many other standard libraries.
-- A React.js context for Authentication, Authorization, Theming and Redux injectable store.
-- Benefits from current and new JupyterLab development, eg edit mode navigation, colored-collapser, collaborative cursor.
-- Authentication via Jupyter tokens.
-- Theming.
-- Terminals.
-
 ## Listed
 
-Listed on:
+We love when people talk about us.
 
-- [reactjs-example](https://reactjsexample.com/react-components-compatible-with-the-jupyter-ecosystem-to-create-your-own-custom-data-product)
+- [Reactjs Example.com](https://reactjsexample.com/react-components-compatible-with-the-jupyter-ecosystem-to-create-your-own-custom-data-product).
+- [How We Made Jupyter Notebooks Load 10 Times Faster](https://www.singlestore.com/blog/how-we-made-notebooks-load-10-times-faster).
diff --git a/docs/docs/components/_category_.yaml b/docs/docs/components/_category_.yaml
@@ -0,0 +1,2 @@
+label: "Components"
+position: 3
diff --git a/docs/docs/components/button/_category_.yml b/docs/docs/components/button/_category_.yml
@@ -1,2 +1,2 @@
 label: "Button"
-position: 3
+position: 5
diff --git a/docs/docs/components/cell/_category_.yml b/docs/docs/components/cell/_category_.yml
@@ -1,2 +1,2 @@
 label: "Cell"
-position: 4
+position: 3
diff --git a/docs/docs/components/cell/index.mdx b/docs/docs/components/cell/index.mdx
@@ -10,9 +10,7 @@ This component displays a Jupyter Cell.
 
 ## With a Jupyter server
 
-<StorybookView 
-    story='components-cell--default'
-/>
+<StorybookView story='components-cell--default' />
 
 ```jsx
 <Jupyter
@@ -46,19 +44,16 @@ plt.show()
 />
 ```
 
-## With in-browser kernel
+## With in-browser Kernel
 
-You can use an in-browser kernel by setting the `lite` property
-of `Jupyter` component:
+You can use an in-browser kernel by setting the `lite` property of `Jupyter` component:
 
 <StorybookView 
     story='components-cell--lite-python'
 />
 
 ```jsx
-<Jupyter
-    lite={true}
->
+<Jupyter lite={true}>
     <Cell
         source={`import sys
 print(f"{sys.platform=}")

diff --git a/docs/docs/components/console/_category_.yml b/docs/docs/components/console/_category_.yml
@@ -1,2 +1,2 @@
 label: "Console"
-position: 6
+position: 3
diff --git a/docs/docs/components/context/_category_.yml b/docs/docs/components/context/_category_.yml
@@ -1,2 +1,2 @@
 label: "Context"
-position: 1
+position: 9
diff --git a/docs/docs/components/context/index.mdx b/docs/docs/components/context/index.mdx
@@ -4,7 +4,7 @@ description: The Context component.
 
 # 🪐 Context
 
-Every component should be wrapped inside a Context to get the needed CSS.
+Every component can be wrapped inside a Context to get the needed CSS.
 
 ```tsx
 root.render(

diff --git a/docs/docs/components/file-manager/_category_.yml b/docs/docs/components/file-manager/_category_.yml
@@ -1,2 +1,2 @@
 label: "File Manager"
-position: 4
+position: 5
diff --git a/docs/docs/components/index.mdx b/docs/docs/components/index.mdx
@@ -0,0 +1,39 @@
+import DocCardList from '@theme/DocCardList';
+import ModalImage from "react-modal-image";
+
+# Components
+
+As a React.js developer, you just write a few lines of code get a live notebook or live cell in your application.
+
+<ModalImage
+  small="https://datalayer-jupyter-examples.s3.amazonaws.com/jupyter-react-snippet.png"
+  large="https://datalayer-jupyter-examples.s3.amazonaws.com/jupyter-react-snippet.png"
+  alt="Jupyter UI Snippet"
+/>
+
+Jupyter UI can be used in any React.js application with the `@datalayer/jupyter-react` npm package.
+
+<ModalImage
+  small="https://datalayer-jupyter-examples.s3.amazonaws.com/jupyter-react-notebook.png"
+  large="https://datalayer-jupyter-examples.s3.amazonaws.com/jupyter-react-notebook.png"
+  alt="Jupyter UI Notebook"
+/>
+
+:::note
+
+The Jupyter UI components support:
+
+- Predefined Zustand actions.
+- Everything is created in a single React tree to ensure Jupyter UI components can use any context created by the host application.
+- IPyWidgets and Panel interactive widgets are supported.
+- Collaborative RTC is also supported.
+- Plays nice with Primer React, Material-UI, Storybook, Docusaurus, Styled Components, Emotion.js... and many other standard libraries.
+- A React.js context for Authentication, Authorization and Theming.
+- Benefits from current and new JupyterLab development, eg edit mode navigation, colored-collapser, collaborative cursor.
+- Authentication via Jupyter tokens.
+- Theming.
+- Terminals.
+
+:::
+
+<DocCardList/>
diff --git a/docs/docs/components/jupyterlab-app/_category_.yml b/docs/docs/components/jupyterlab-app/_category_.yml
@@ -0,0 +1,2 @@
+label: "JupyterLab App"
+position: 13
diff --git a/docs/docs/components/jupyterlabapp/index.mdx → .../docs/components/jupyterlab-app/index.mdx b/docs/docs/components/jupyterlabapp/index.mdx → .../docs/components/jupyterlab-app/index.mdx
diff --git a/docs/docs/components/jupyterlabapp/_category_.yml b/docs/docs/components/jupyterlabapp/_category_.yml
diff --git a/docs/docs/components/kernel/_category_.yml b/docs/docs/components/kernel/_category_.yml
@@ -1,2 +1,2 @@
 label: "Kernels"
-position: 4
+position: 7
diff --git a/docs/docs/components/lumino/_category_.yml b/docs/docs/components/lumino/_category_.yml
@@ -1,2 +1,2 @@
 label: "Lumino"
-position: 2
+position: 14
diff --git a/docs/docs/components/native/_category_.yml b/docs/docs/components/native/_category_.yml
@@ -1,2 +1,2 @@
 label: "Native"
-position: 8
+position: 9
diff --git a/docs/docs/components/notebook/index.mdx b/docs/docs/components/notebook/index.mdx
@@ -16,7 +16,7 @@ The below picture is an example of Notebook into a React.js component.
   alt="Jupyter UI Notebook"
 />
 
-This is what it takes to create a Notebook. In this first example, the Jupyter Server will be fetched for the `test.ipynb` notebook "ipynb" file content.
+In this first example, the Jupyter Server will be fetched for the `test.ipynb` notebook `ipynb` file content.
 
 ```jsx
 <Jupyter terminals={true} collaborative={true}>
@@ -35,13 +35,7 @@ import nbformat from "./NotebookExample.ipynb.json";
 </Jupyter>
 ```
 
-For IPyWidgets, use the following properties:
-
-- `bundledIPyWidgets`: List of module name, version and exports.
-- `externalIPyWidgets`: List of module name and version to be loaded from public CDNs.
-- `ipywidgets`: `lab` or `classic` (deprecated, will be soon removed). Please use `lab`
-
-The available properties for the Notebook component are available on this [TypeDoc page](https://typedoc.datalayer.tech/datalayer/jupyter-react/0.8.1/types/INotebookProps.html).
+The available properties for the Notebook component are listed on the [TypeDoc page](https://typedoc.datalayer.tech/datalayer/jupyter-react/0.9.0/types/INotebookProps.html).
 
 ## With a Jupyter server
 
@@ -62,7 +56,11 @@ You can set the following props to connect it to a running Jupyter Server:
 - `jupyterServerUrl`: The server URL
 - `jupyterServerToken`: The server authentication token
 
-> Your server will likely need to accept connection from external client.
+:::note
+
+Your server will likely to accept connections from external client.
+
+:::
 
 ## With in-browser kernel
 
@@ -88,7 +86,7 @@ you can simply set `lite` to `true`:
             cell_type: 'code',
             outputs: [],
             source:
-              "import piplite\nawait piplite.install('ipywidgets')",
+              "import micropip\nawait micropip.install('ipywidgets')",
           },
           {
             cell_type: 'code',

diff --git a/docs/docs/components/terminal/_category_.yml b/docs/docs/components/terminal/_category_.yml
@@ -1,2 +1,2 @@
 label: "Terminal"
-position: 5
+position: 4
diff --git a/docs/docs/components/viewer/_category_.yml b/docs/docs/components/viewer/_category_.yml
@@ -1,2 +1,2 @@
 label: "Viewer"
-position: 3
+position: 6
diff --git a/docs/docs/demos/_category_.yaml b/docs/docs/demos/_category_.yaml
@@ -0,0 +1,2 @@
+label: "Demos"
+position: 9
diff --git a/docs/docs/demos/cell/index.mdx b/docs/docs/demos/cell/index.mdx
@@ -2,21 +2,17 @@
 description: A demonstation of the Cell component.
 ---
 
-# Cell Demo
-
 import JupyterCell from '@theme/JupyterCell';
 
-:::tip
+# Cell Demo
 
-Type your code in the below cell and hit `SHIFT+ENTER` to execute your  code.
+:::tip
 
-> ✨ This is fast, isn't it?
+✨ Type your code in the below cell and hit `SHIFT+ENTER` to execute your  code.
 
 :::
 
 <JupyterCell
-  jupyterServerUrl='https://oss.datalayer.run/api/jupyter-server'
-  jupyterServerToken='60c1661cc408f978c309d04157af55c9588ff9557c9380e4fb50785750703da6'
   source= {`import numpy as np
 import matplotlib.pyplot as plt
 x1 = np.linspace(0.0, 5.0)

diff --git a/docs/docs/demos/index.mdx b/docs/docs/demos/index.mdx
@@ -0,0 +1,5 @@
+import DocCardList from '@theme/DocCardList';
+
+# Demos
+
+<DocCardList/>
diff --git a/docs/docs/deployments/_category_.yaml b/docs/docs/deployments/_category_.yaml
@@ -0,0 +1,2 @@
+label: "Deployments"
+position: 6
diff --git a/docs/docs/deployments/index.mdx b/docs/docs/deployments/index.mdx
@@ -0,0 +1,5 @@
+import DocCardList from '@theme/DocCardList';
+
+# Deployments
+
+<DocCardList/>