Various enhancements related to menu naming, READMEs... (jupyterlab#71)

* Various enhancement related to menu naming, READMEs... * More alignement on namings + use window.alert to give more feedback to the user * More work to align naming and menus * rename server-estension.ts * fix embedme * run embedme * fix embedme * more lint * disable prettier in server README * force ci * Update README.md Co-Authored-By: Jeremy Tuloup <[email protected]> * Update README.md Co-Authored-By: Jeremy Tuloup <[email protected]> * Update advanced/kernel-output/README.md Co-Authored-By: Jeremy Tuloup <[email protected]> * Update basics/datagrid/README.md Co-Authored-By: Jeremy Tuloup <[email protected]> * Update basics/hello-world/README.md Co-Authored-By: Jeremy Tuloup <[email protected]> * Update basics/signals/README.md Co-Authored-By: Jeremy Tuloup <[email protected]> * Update basics/signals/README.md Co-Authored-By: Jeremy Tuloup <[email protected]> * Update basics/signals/README.md Co-Authored-By: Jeremy Tuloup <[email protected]> * Update main-menu/README.md Co-Authored-By: Jeremy Tuloup <[email protected]> * Update state/src/index.ts Co-Authored-By: Jeremy Tuloup <[email protected]> * Ensure embedme does not run ont node_modules README.md files. * document jlpm instead of yarn * typos in README * Fix settings example * trigger CI build * Remove alert on startup * Run embedmee * Disable alert for settings Co-authored-by: Jeremy Tuloup <[email protected]>
mateusz-garlacz · Mar 4, 2020 · fbef6e8 · fbef6e8
1 parent c555052
commit fbef6e8
Show file tree

Hide file tree

Showing 41 changed files with 455 additions and 287 deletions.
diff --git a/.gitignore b/.gitignore
@@ -6,3 +6,5 @@ node_modules/
 .ipynb_checkpoints
 *.tsbuildinfo
 *.lock
+# Ensure embedme does not run ont node_modules README.md files.
+**/node_modules/**/README.md
diff --git a/README.md b/README.md
@@ -10,22 +10,18 @@ The goal of this repository is to show how to develop extensions for [JupyterLab
 To get started:
 
 ```bash
-git clone https://github.com/jtpio/jupyterlab-extension-examples.git &&
+git clone https://github.com/jtpio/jupyterlab-extension-examples.git && \
   cd jupyterlab-extension-examples && \
   conda env create && \
   conda activate jupyterlab-extension-examples && \
   cd basics/hello-world && \
   jlpm && \
   jlpm run build && \
-  jupyter labextension link .
-
-# In another terminal
-jupyter lab --watch
+  jupyter labextension link . && \
+  jupyter lab
 ```
 
-The examples currently target **JupyterLab 2.x**.
-
-If you would like to use the examples with JupyterLab 1.x, check out the [1.x branch](https://github.com/jtpio/jupyterlab-extension-examples/tree/1.x). Note that the `1.x` branch is not updated anymore.
+The examples currently target **JupyterLab 2.x**. If you would like to use the examples with JupyterLab 1.x, check out the [1.x branch](https://github.com/jtpio/jupyterlab-extension-examples/tree/1.x). Note that the `1.x` branch is not updated anymore.
 
 ## Develop by Examples
 
@@ -57,80 +53,110 @@ You can expect from each example:
 
 We have structured the examples based on the [extension points](https://jupyterlab.readthedocs.io/en/stable/developer/extension_points.html). Browse the previews below or skip them and [jump directly to the sections for developers](#prerequisites).
 
+You are welcome to open any [issue](https://github.com/jtpio/jupyterlab-extension-examples/issues) or [pull request](https://github.com/jtpio/jupyterlab-extension-examples/pulls).
+
 ## Basic
 
 ### [Hello World](basics/hello-world)
 
+Set up the development environment and print to the console.
+
 [![Hello World](basics/hello-world/preview.png)](basics/hello-world)
 
 ### [Signals](basics/signals)
 
+Use Signals to allow Widgets communicate with each others.
+
 [![Button with Signal](basics/signals/preview.png)](basics/signals)
 
 ### [Datagrid](basics/datagrid)
 
-[![Datagrid](basics/datagrid/preview.png)](basics/datagrid) |
+Display a Datagrid as a Lumino Widget.
+
+[![Datagrid](basics/datagrid/preview.png)](basics/datagrid)
 
 ## Command Palette
 
 ### [Command Palette](command-palette)
 
+Register commands in the Command Palette.
+
 [![Commmand Palette](command-palette/preview.png)](command-palette)
 
 ## Commands
 
 ### [Commands](commands)
 
+Extend the main app with a Command.
+
 [![Commmand example](commands/preview.png)](commands)
 
 ## Launcher
 
 ### [Launcher](launcher)
 
+Start your extension from the Launcher.
+
 [![Launcher](launcher/preview.gif)](launcher)
 
 ## Menus
 
 ### [Main Menu](main-menu)
 
+Add a Menu to the main app.
+
 [![Main Menu](main-menu/preview.png)](main-menu)
 
 ## Settings
 
 ### [Settings](settings)
 
+Create and use new Settings for your extension.
+
 [![Settings](settings/preview.gif)](settings)
 
 ## State
 
 ### [State](state)
 
+Use State persistence in an extension.
+
 [![State](state/preview.gif)](state)
 
 ## React
 
 ### [React Widget](react/react-widget)
 
+Create a React.js Widget in JupyterLab.
+
 [![react-widget](react/react-widget/preview.gif)](react/react-widget)
 
 ## Widget Tracker
 
 ### [Widgets](widget-tracker/widgets)
 
+Add a new Widget element to the main window.
+
 [![Custom Tab](widget-tracker/widgets/preview.png)](widget-tracker/widgets)
 
 ## Advanced
 
 ### [Kernel Output](advanced/kernel-output)
 
+Render kernel messages in an OuputArea.
+
 [![OutputArea class](advanced/kernel-output/preview.gif)](advanced/kernel-output)
 
 ### [Kernel Messaging](advanced/kernel-messaging)
 
+Interact with a kernel from an extension.
+
 [![Kernel Messages](advanced/kernel-messaging/preview.gif)](advanced/kernel-messaging)
 
 ### [Server Hello World](advanced/server-extension)
 
+Create a minimal extension with backend (i.e. server) and frontend parts.
+
 [![Server Hello World](advanced/server-extension/preview.png)](advanced/server-extension)
 
 ## Prerequisites
@@ -151,7 +177,7 @@ conda env create && \
 
 ## Develop and Use the Examples
 
-### Build and link all examples at once
+### Build and Link all Examples at once
 
 ```bash
 jlpm
@@ -167,7 +193,7 @@ To clean the lib folders:
 jlpm clean-ext
 ```
 
-### Build and link one example
+### Build and Link one Example
 
 Go to the example directory you want to install, e.g. `cd ./basics/hello-world`, and run the following commands:
 
@@ -184,15 +210,37 @@ jlpm run build
 jupyter lab build
 ```
 
-Start JupyterLab in watch mode:
+You can now start JupyterLab and check if your extension is working fine:
+
+```bash
+jupyter lab
+```
+
+### Change the Sources
+
+If you want to develop and iterate on the code, you will need to open 2 terminals.
+
+In terminal 1, go to the extension folder and run the following:
+
+```bash
+jlpm watch
+```
+
+Then in terminal 2, start JupyterLab with the watch flag:
 
 ```bash
 jupyter lab --watch
 ```
 
+From there, you can change your extension source code, it will be recompiled,
+and you can refresh your browser to see your changes.
+
+We are using [embedme](https://github.com/zakhenry/embedme) to embed code snippets into the markdown READMEs. If you make changes to the source code, ensure you update the README and run `jlpm embedme` from the root of the repository to regenerate the READMEs.
+
 ## Install a Published Extension
 
-Once your extension is published (outside of this scope), you can install it with the following command:
+Once your extension is published (outside of this scope), you can install it
+with the following command:
 
 ```bash
 jupyter labextension install <published_extension>
@@ -206,8 +254,6 @@ level components that can be used are text editors, terminals, notebooks, intera
 filebrowser, renderers for different file formats that provide access to an enormous ecosystem
 of libraries from different languages.
 
-## JupyterLab Documentation
-
 Complementary to these examples, you can rely on the official JupyterLab documentation.
 
 - [Extension Developer Guide](https://jupyterlab.readthedocs.io/en/stable/developer/extension_dev.html)

diff --git a/advanced/kernel-messaging/README.md b/advanced/kernel-messaging/README.md
@@ -1,5 +1,7 @@
 # Kernel Messaging
 
+> Interact with a kernel from an extension.
+
 - [Component Overview](#component-overview)
 - [Initializing and managing a kernel session (panel.ts)](#initializing-and-managing-a-kernel-session-panelts)
 - [Executing code and retrieving messages from a kernel (model.ts)](#executing-code-and-retrieving-messages-from-a-kernel-modelts)
@@ -18,7 +20,7 @@ start a kernel and send some code to be executed by it.
 
 This example is structured in four files:
 
-- `index.ts`: the JupyterLab frontend plugin that initializes the plugin and registers commands, add a menu entry and a launcher item,
+- `index.ts`: the JupyterLab frontend plugin that initializes the plugin and registers commands, add a menu entry and a launcher item
 - `panel.ts`: a panel class that is responsible to initialize and hold the kernel session, widgets and model
 - `model.ts`: a KernelModel class that is responsible to execute code on the kernel and to store the execution result
 - `widget.tsx`: a KernelView class that is responsible to provide visual elements that trigger the kernel model and display its results
@@ -27,7 +29,7 @@ The `KernelView` displays the `KernelModel` thanks to some React HTML elements a
 gets updated when the `KernelModel` state changes, i.e. retrieves a new
 execution result.
 
-## Initializing and managing a kernel session (`panel.ts`)
+## Initializing and managing a Kernel Session (`panel.ts`)
 
 Jupyterlab provides a class `SessionContext`
 ([see the documentation](https://jupyterlab.github.io/jupyterlab/apputils/classes/sessioncontext.html))
@@ -39,7 +41,7 @@ that manages a single kernel session. Here is the code to initialize such sessio
 this._sessionContext = new SessionContext({
   sessionManager: manager.sessions,
   specsManager: manager.kernelspecs,
-  name: 'Example'
+  name: 'Extension Examples'
 });
 ```
 
@@ -86,13 +88,13 @@ export class ExamplePanel extends StackedPanel {
     super();
     this.addClass(PANEL_CLASS);
     this.id = 'kernel-messaging-panel';
-    this.title.label = 'Example View';
+    this.title.label = 'Kernel Messaging Example View';
     this.title.closable = true;
 
     this._sessionContext = new SessionContext({
       sessionManager: manager.sessions,
       specsManager: manager.kernelspecs,
-      name: 'Example'
+      name: 'Extension Examples'
     });
 
     this._model = new KernelModel(this._sessionContext);
@@ -133,7 +135,7 @@ export class ExamplePanel extends StackedPanel {
 }
 ```
 
-## Executing code and retrieving messages from a kernel (`model.ts`)
+## Executing code and retrieving messages from a Kernel (`model.ts`)
 
 Once a kernel is initialized and ready, code can be executed with the following snippet:
 

diff --git a/advanced/kernel-messaging/src/index.ts b/advanced/kernel-messaging/src/index.ts
@@ -39,7 +39,7 @@ function activate(
 ) {
   const manager = app.serviceManager;
   const { commands, shell } = app;
-  const category = 'Example';
+  const category = 'Extension Examples';
 
   // Add launcher
   if (launcher) {
@@ -57,12 +57,12 @@ function activate(
 
   // add menu tab
   const exampleMenu = new Menu({ commands });
-  exampleMenu.title.label = 'Example';
+  exampleMenu.title.label = 'Kernel Messaging';
   mainMenu.addMenu(exampleMenu);
 
   // add commands to registry
   commands.addCommand(CommandIDs.create, {
-    label: 'kernel-messaging: open Panel',
+    label: 'Open the Kernel Messaging Panel',
     caption: 'Open the Kernel Messaging Panel',
     execute: createPanel
   });

diff --git a/advanced/kernel-messaging/src/panel.ts b/advanced/kernel-messaging/src/panel.ts
@@ -27,13 +27,13 @@ export class ExamplePanel extends StackedPanel {
     super();
     this.addClass(PANEL_CLASS);
     this.id = 'kernel-messaging-panel';
-    this.title.label = 'Example View';
+    this.title.label = 'Kernel Messaging Example View';
     this.title.closable = true;
 
     this._sessionContext = new SessionContext({
       sessionManager: manager.sessions,
       specsManager: manager.kernelspecs,
-      name: 'Example'
+      name: 'Extension Examples'
     });
 
     this._model = new KernelModel(this._sessionContext);

diff --git a/advanced/kernel-output/README.md b/advanced/kernel-output/README.md
@@ -1,4 +1,6 @@
-# Kernel Output - Simple Notebook-style Rendering
+# Kernel Output
+
+> Render kernel messages in an OuputArea.
 
 - [Code structure](#code-structure)
 - [Initializing a Kernel Session](#initializing-a-kernel-session)
@@ -53,7 +55,7 @@ the kernel) is started with these lines:
 this._sessionContext = new SessionContext({
   sessionManager: manager.sessions,
   specsManager: manager.kernelspecs,
-  name: 'Example'
+  name: 'Kernel Output'
 });
 ```
 
@@ -227,8 +229,8 @@ and display:
 // src/index.ts#L69-L89
 
 commands.addCommand(CommandIDs.execute, {
-  label: 'kernel-output: Execute Code',
-  caption: 'Execute Code',
+  label: 'Contact Kernel and Execute Code',
+  caption: 'Contact Kernel and Execute Code',
   execute: async () => {
     // Create the panel if it does not exist
     if (!panel) {

diff --git a/advanced/kernel-output/src/index.ts b/advanced/kernel-output/src/index.ts
@@ -44,7 +44,7 @@ function activate(
 ) {
   const manager = app.serviceManager;
   const { commands, shell } = app;
-  const category = 'Example';
+  const category = 'Extension Examples';
 
   let panel: ExamplePanel;
 
@@ -56,19 +56,19 @@ function activate(
 
   // add menu tab
   const exampleMenu = new Menu({ commands });
-  exampleMenu.title.label = 'Example';
+  exampleMenu.title.label = 'Kernel Output';
   mainMenu.addMenu(exampleMenu);
 
   // add commands to registry
   commands.addCommand(CommandIDs.create, {
-    label: 'kernel-output: Open Panel',
+    label: 'Open the Kernel Output Panel',
     caption: 'Open the Kernel Output Panel',
     execute: createPanel
   });
 
   commands.addCommand(CommandIDs.execute, {
-    label: 'kernel-output: Execute Code',
-    caption: 'Execute Code',
+    label: 'Contact Kernel and Execute Code',
+    caption: 'Contact Kernel and Execute Code',
     execute: async () => {
       // Create the panel if it does not exist
       if (!panel) {

diff --git a/advanced/kernel-output/src/panel.ts b/advanced/kernel-output/src/panel.ts
@@ -30,13 +30,13 @@ export class ExamplePanel extends StackedPanel {
     super();
     this.addClass(PANEL_CLASS);
     this.id = 'kernel-output-panel';
-    this.title.label = 'Example View';
+    this.title.label = 'Kernel Output Example View';
     this.title.closable = true;
 
     this._sessionContext = new SessionContext({
       sessionManager: manager.sessions,
       specsManager: manager.kernelspecs,
-      name: 'Example'
+      name: 'Kernel Output'
     });
 
     this._outputareamodel = new OutputAreaModel();

diff --git a/advanced/server-extension/LICENSE b/advanced/server-extension/LICENSE
@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2019, my_name
+Copyright (c) 2019, JupyterLab
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without