Skip to content

Commit d270a96

Browse files
andyjakubowskiandyjakubowski
committed
Add CONTRIBUTING.md
Signed-off-by: Andy Jakubowski <[email protected]>
1 parent ae02719 commit d270a96

File tree

2 files changed

+143
-144
lines changed

2 files changed

+143
-144
lines changed

‎CONTRIBUTING.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# Contributing to `jupyterlab-deepnote`
2+
3+
## Development install
4+
5+
Note: You will need NodeJS to build the extension package.
6+
7+
Use any Python environment and dependency manager you like, for example [uv](https://docs.astral.sh/uv/getting-started/installation/):
8+
9+
```shell
10+
curl -LsSf https://astral.sh/uv/install.sh | sh
11+
```
12+
13+
Create a Python environment in the project directory:
14+
15+
```shell
16+
uv venv --python 3.12 --managed-python
17+
```
18+
19+
Activate the Python environment:
20+
21+
```shell
22+
source .venv/bin/activate
23+
```
24+
25+
Install `jupyterlab`. The extension package itself doesn’t depend on `jupyterlab`, you just need `jupyterlab` in the environment where you will be testing the extension.
26+
27+
```shell
28+
uv pip install jupyterlab
29+
```
30+
31+
**Configure Access to @deepnote/blocks Package**
32+
33+
The `@deepnote/blocks` package is published on GitHub Packages. To install it, you'll need to authenticate with GitHub:
34+
35+
1. Create a GitHub Personal Access Token (classic) with `read:packages` scope:
36+
- Go to https://github.com/settings/tokens
37+
- Click "Generate new token (classic)"
38+
- Select the `read:packages` scope
39+
- Generate and copy the token
40+
41+
2. Set the `GITHUB_TOKEN` environment variable to ensure `jlpm` (which is a wrapper around Yarn) can download the `@deepnote/blocks` package from the GitHub package registry. You can export the variable in `.zshrc` (or by reading a `~/.env` file):
42+
```shell
43+
export GITHUB_TOKEN=your_token_here
44+
```
45+
Replace `YOUR_TOKEN_HERE` with your actual token.
46+
47+
Install the extension package in editable mode. It installs the package’s dependencies, too:
48+
49+
```shell
50+
uv pip install --editable . --verbose
51+
```
52+
53+
Link your development version of the extension with JupyterLab:
54+
55+
```shell
56+
jupyter labextension develop . --overwrite
57+
```
58+
59+
Enable the extension in Jupyter Server:
60+
61+
```shell
62+
jupyter server extension enable jupyterlab_deepnote
63+
```
64+
65+
Rebuild the extension’s Typescript source after making changes:
66+
67+
```shell
68+
jlpm run watch
69+
```
70+
71+
The `jlpm` command is JupyterLab's pinned version of
72+
[yarn](https://yarnpkg.com/) that is installed with JupyterLab. You may use
73+
`yarn` or `npm` instead of `jlpm` below.
74+
75+
In a separate terminal, run `jupyter lab`. You can add the `--debug` option to see HTTP requests in the logs, which can be helpful for debugging.
76+
77+
```shell
78+
jupyter lab --debug
79+
```
80+
81+
You can watch the source directory and run JupyterLab at the same time in different terminals to watch for changes in the extension's source and automatically rebuild the extension.
82+
83+
```bash
84+
# Watch the source directory in one terminal, automatically rebuilding when needed
85+
jlpm watch
86+
# Run JupyterLab in another terminal
87+
jupyter lab
88+
```
89+
90+
With the watch command running, every saved change will immediately be built locally and available in your running JupyterLab. Refresh JupyterLab to load the change in your browser (you may need to wait several seconds for the extension to be rebuilt).
91+
92+
By default, the `jlpm build` command generates the source maps for this extension to make it easier to debug using the browser dev tools. To also generate source maps for the JupyterLab core extensions, you can run the following command:
93+
94+
```bash
95+
jupyter lab build --minimize=False
96+
```
97+
98+
## Development uninstall
99+
100+
```bash
101+
# Server extension must be manually disabled in develop mode
102+
jupyter server extension disable jupyterlab_deepnote
103+
pip uninstall jupyterlab_deepnote
104+
```
105+
106+
In development mode, you will also need to remove the symlink created by `jupyter labextension develop`
107+
command. To find its location, you can run `jupyter labextension list` to figure out where the `labextensions`
108+
folder is located. Then you can remove the symlink named `jupyterlab-deepnote` within that folder.
109+
110+
## Testing the extension
111+
112+
### Server tests
113+
114+
This extension is using [Pytest](https://docs.pytest.org/) for Python code testing.
115+
116+
Install test dependencies (needed only once):
117+
118+
```sh
119+
pip install -e ".[test]"
120+
# Each time you install the Python package, you need to restore the front-end extension link
121+
jupyter labextension develop . --overwrite
122+
```
123+
124+
To execute them, run:
125+
126+
```sh
127+
pytest -vv -r ap --cov jupyterlab_deepnote
128+
```
129+
130+
### Frontend tests
131+
132+
This extension is using [Jest](https://jestjs.io/) for JavaScript code testing.
133+
134+
To execute them, execute:
135+
136+
```sh
137+
jlpm
138+
jlpm test
139+
```
140+
141+
## Packaging the extension
142+
143+
See [RELEASE](RELEASE.md)

‎README.md‎

Lines changed: 0 additions & 144 deletions
Original file line numberDiff line numberDiff line change
@@ -44,147 +44,3 @@ the frontend extension, check the frontend extension is installed:
4444
```bash
4545
jupyter labextension list
4646
```
47-
48-
## Contributing
49-
50-
### Development install
51-
52-
Note: You will need NodeJS to build the extension package.
53-
54-
Use any Python environment and dependency manager you like, for example [uv](https://docs.astral.sh/uv/getting-started/installation/):
55-
56-
```shell
57-
curl -LsSf https://astral.sh/uv/install.sh | sh
58-
```
59-
60-
Create a Python environment in the project directory:
61-
62-
```shell
63-
uv venv --python 3.12 --managed-python
64-
```
65-
66-
Activate the Python environment:
67-
68-
```shell
69-
source .venv/bin/activate
70-
```
71-
72-
Install `jupyterlab`. The extension package itself doesn’t depend on `jupyterlab`, you just need `jupyterlab` in the environment where you will be testing the extension.
73-
74-
```shell
75-
uv pip install jupyterlab
76-
```
77-
78-
**Configure Access to @deepnote/blocks Package**
79-
80-
The `@deepnote/blocks` package is published on GitHub Packages. To install it, you'll need to authenticate with GitHub:
81-
82-
1. Create a GitHub Personal Access Token (classic) with `read:packages` scope:
83-
- Go to https://github.com/settings/tokens
84-
- Click "Generate new token (classic)"
85-
- Select the `read:packages` scope
86-
- Generate and copy the token
87-
88-
2. Set the `GITHUB_TOKEN` environment variable to ensure `jlpm` (which is a wrapper around Yarn) can download the `@deepnote/blocks` package from the GitHub package registry. You can export the variable in `.zshrc` (or by reading a `~/.env` file):
89-
```shell
90-
export GITHUB_TOKEN=your_token_here
91-
```
92-
Replace `YOUR_TOKEN_HERE` with your actual token.
93-
94-
Install the extension package in editable mode. It installs the package’s dependencies, too:
95-
96-
```shell
97-
uv pip install --editable . --verbose
98-
```
99-
100-
Link your development version of the extension with JupyterLab:
101-
102-
```shell
103-
jupyter labextension develop . --overwrite
104-
```
105-
106-
Enable the extension in Jupyter Server:
107-
108-
```shell
109-
jupyter server extension enable jupyterlab_deepnote
110-
```
111-
112-
Rebuild the extension’s Typescript source after making changes:
113-
114-
```shell
115-
jlpm run watch
116-
```
117-
118-
The `jlpm` command is JupyterLab's pinned version of
119-
[yarn](https://yarnpkg.com/) that is installed with JupyterLab. You may use
120-
`yarn` or `npm` instead of `jlpm` below.
121-
122-
In a separate terminal, run `jupyter lab`. You can add the `--debug` option to see HTTP requests in the logs, which can be helpful for debugging.
123-
124-
```shell
125-
jupyter lab --debug
126-
```
127-
128-
You can watch the source directory and run JupyterLab at the same time in different terminals to watch for changes in the extension's source and automatically rebuild the extension.
129-
130-
```bash
131-
# Watch the source directory in one terminal, automatically rebuilding when needed
132-
jlpm watch
133-
# Run JupyterLab in another terminal
134-
jupyter lab
135-
```
136-
137-
With the watch command running, every saved change will immediately be built locally and available in your running JupyterLab. Refresh JupyterLab to load the change in your browser (you may need to wait several seconds for the extension to be rebuilt).
138-
139-
By default, the `jlpm build` command generates the source maps for this extension to make it easier to debug using the browser dev tools. To also generate source maps for the JupyterLab core extensions, you can run the following command:
140-
141-
```bash
142-
jupyter lab build --minimize=False
143-
```
144-
145-
### Development uninstall
146-
147-
```bash
148-
# Server extension must be manually disabled in develop mode
149-
jupyter server extension disable jupyterlab_deepnote
150-
pip uninstall jupyterlab_deepnote
151-
```
152-
153-
In development mode, you will also need to remove the symlink created by `jupyter labextension develop`
154-
command. To find its location, you can run `jupyter labextension list` to figure out where the `labextensions`
155-
folder is located. Then you can remove the symlink named `jupyterlab-deepnote` within that folder.
156-
157-
### Testing the extension
158-
159-
#### Server tests
160-
161-
This extension is using [Pytest](https://docs.pytest.org/) for Python code testing.
162-
163-
Install test dependencies (needed only once):
164-
165-
```sh
166-
pip install -e ".[test]"
167-
# Each time you install the Python package, you need to restore the front-end extension link
168-
jupyter labextension develop . --overwrite
169-
```
170-
171-
To execute them, run:
172-
173-
```sh
174-
pytest -vv -r ap --cov jupyterlab_deepnote
175-
```
176-
177-
#### Frontend tests
178-
179-
This extension is using [Jest](https://jestjs.io/) for JavaScript code testing.
180-
181-
To execute them, execute:
182-
183-
```sh
184-
jlpm
185-
jlpm test
186-
```
187-
188-
### Packaging the extension
189-
190-
See [RELEASE](RELEASE.md)

0 commit comments

Comments
 (0)