Skip to content

Commit 4585387

Browse files
Update main README and hello-world README (#277)
* docs(hello-world README): made intro section more visible and expanded on it for clarity * docs(hello-world README): moved image below TOC for clarity; elaborated alt text * docs(hello-world README): labeled the TOC for clarity; changed some heading names for clarity * docs(READMEs): clarify how the TL;DR and hello-world examples relate Adds a section to the hello-world example, 'Modify the extension', to indicate where this example picks up after the TL;DR leaves off. Also adds steps to the TL;DR to clarify what the code snippet is doing and to mention that more details are available in hello-world, including the information on the extension template. * docs(hello-world README): adds --trust flag to copier command fixes this error:--trustcopier copy/update * docs(hello-world README): adds step to create yarn.lock file matches updated steps in the main README.md. Fixes yarn error message * docs(hello-world README): changed file name the first command installs dependencies specified in pyproject.toml, instead of setup.py
1 parent 007ef89 commit 4585387

File tree

2 files changed

+22
-11
lines changed

2 files changed

+22
-11
lines changed

README.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,10 @@
4646

4747
The goal of this repository is to show how to develop extensions for [JupyterLab](https://github.com/jupyterlab/jupyterlab), presented as short tutorial series.
4848

49-
To get started:
49+
**Quick start:**
50+
- Install, build, and run the `hello-world` extension example in JupyterLab by copying the code below.
51+
- This corresponds to the first three sections of the [hello-world extension tutorial](hello-world/README.md). Read these sections for additional details on what these commands are doing and how to use the JupyterLab extension template.
52+
- Continue with the tutorial at the [Modify the extension](hello-world/README.md#modify-the-extension) section, if desired.
5053

5154
```bash
5255
# clone the repository

hello-world/README.md

Lines changed: 18 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,18 @@
11
# Hello World
22

3-
> Set up the development environment and print to the console.
3+
In this example, you will learn how to set up the extension development environment and create a minimal extension that prints to the console.
44

5-
![hello world example](./preview.png)
5+
**Table of Contents**
66

7-
- [The template folder structure](#the-template-folder-structure)
8-
- [A minimal extension that prints to the browser console](#a-minimal-extension-that-prints-to-the-browser-console)
9-
- [Building and Installing an Extension](#building-and-installing-an-extension)
7+
- [The JupyterLab extension template](#the-jupyterlab-extension-template)
8+
- [Overview of the hello-world extension code](#overview-of-the-hello-world-extension-code)
9+
- [Build and installing the hello-world extension](#build-and-install-the-hello-world-extension)
10+
- [Modify the extension](#modify-the-extension)
11+
- [Where to go next](#where-to-go-next)
1012

11-
## The template folder structure
13+
![Screen capture of the JupyterLab web interface with the browser console open below, showing the log output from the hello-world JupyterLab extension](./preview.png)
14+
15+
## The JupyterLab extension template
1216

1317
Writing a JupyterLab extension usually starts from a configurable template. It
1418
can be downloaded with the [`copier`](https://copier.readthedocs.io/) tool and the following command:
@@ -17,7 +21,7 @@ can be downloaded with the [`copier`](https://copier.readthedocs.io/) tool and t
1721
pip install "copier~=9.2" jinja2-time
1822
mkdir my_extension
1923
cd my_extension
20-
copier copy https://github.com/jupyterlab/extension-template .
24+
copier copy --trust https://github.com/jupyterlab/extension-template .
2125
```
2226

2327
You will be asked for some basic information that could for example be setup
@@ -133,7 +137,7 @@ Those files can be separated in to 5 groups:
133137

134138
The following sections will walk you through the extension code files.
135139

136-
## A minimal extension that prints to the browser console
140+
## Overview of the hello-world extension code
137141

138142
Start with the file `src/index.ts`. This typescript file contains the main
139143
logic of the extension. It begins with the following import section:
@@ -208,13 +212,15 @@ JupyterLab, which is done with the line `export default plugin`.
208212

209213
Now that the extension code is ready, you need to install it within JupyterLab.
210214

211-
## Building and Installing an Extension
215+
## Build and install the hello-world extension
212216

213217
These are the instructions on how your extension can be installed for development:
214218

215219
> You will need NodeJS to build the extension package.
216220
217221
```bash
222+
# Required to identify the project for Yarn 3
223+
touch yarn.lock
218224
# Install package in development mode
219225
pip install -e .
220226
# Link your development version of the extension with JupyterLab
@@ -228,7 +234,7 @@ jlpm run build
228234
> `yarn` or `npm` in lieu of `jlpm` below.
229235
230236
The first command installs the dependencies that are specified in the
231-
`setup.py` file and in `package.json`. Among the dependencies are also all of the `JupyterLab` components that you want to use in your project.
237+
`pyproject.toml` file and in `package.json`. Among the dependencies are also all of the `JupyterLab` components that you want to use in your project.
232238

233239
It then runs the build script. In that step, the TypeScript code gets
234240
converted to javascript using the compiler `tsc` and stored in a `lib`
@@ -262,6 +268,8 @@ open the console pressing the `F12` key. You should see something like:
262268
JupyterLab extension hello-world is activated
263269
```
264270

271+
## Modify the extension
272+
265273
Your extension works but it is not doing much. Let's modify the source code
266274
a bit. Simply replace the `activate` function with the following lines:
267275

0 commit comments

Comments
 (0)