Skip to content

Commit 125f95d

Browse files
andyjakubowskijamesbhobbs
andyjakubowski
and
jamesbhobbs
authored
docs: update OSS docs (#34)
* Add CONTRIBUTING.md Signed-off-by: Andy Jakubowski <hello@andyjakubowski.com> * docs: update README, CONTRIBUTING, RELEASE Signed-off-by: Andy Jakubowski <hello@andyjakubowski.com> * Fix heading Signed-off-by: Andy Jakubowski <hello@andyjakubowski.com> * Update Python version Signed-off-by: Andy Jakubowski <hello@andyjakubowski.com> * Update readme Signed-off-by: Andy Jakubowski <hello@andyjakubowski.com> * Remove conda forge release instructions Conda should not be a recommended package registry target Signed-off-by: Andy Jakubowski <hello@andyjakubowski.com> * Update required JupyterLab version to 4.5 We need that version because it adds support for custom content providers, something our extension depends on: https://jupyterlab.readthedocs.io/en/stable/extension/extension_points.html#content-provisioning Signed-off-by: Andy Jakubowski <hello@andyjakubowski.com> --------- Signed-off-by: Andy Jakubowski <hello@andyjakubowski.com> Co-authored-by: James Hobbs <15235276+jamesbhobbs@users.noreply.github.com>
1 parent 295a36c commit 125f95d

File tree

3 files changed

+200
-166
lines changed

3 files changed

+200
-166
lines changed

‎CONTRIBUTING.md‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# Scope
2+
3+
This document is intended for contributors and maintainers working on the extension's source code. For general usage and installation instructions, please refer to the README.
4+
5+
# Contributing to `jupyterlab-deepnote`
6+
7+
## Development install
8+
9+
Note: You will need NodeJS to build the extension package.
10+
11+
Use any Python environment and dependency manager you like, for example [uv](https://docs.astral.sh/uv/getting-started/installation/):
12+
13+
```shell
14+
curl -LsSf https://astral.sh/uv/install.sh | sh
15+
```
16+
17+
Create a Python environment in the project directory:
18+
19+
```shell
20+
uv venv --python 3.12 --managed-python
21+
```
22+
23+
Activate the Python environment:
24+
25+
```shell
26+
source .venv/bin/activate
27+
```
28+
29+
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.
30+
31+
```shell
32+
uv pip install jupyterlab
33+
```
34+
35+
### Configure Access to @deepnote/blocks Package
36+
37+
The `@deepnote/blocks` package is published on GitHub Packages. To install it, you'll need to authenticate with GitHub:
38+
39+
1. Create a GitHub Personal Access Token (classic) with `read:packages` scope:
40+
- Go to https://github.com/settings/tokens
41+
- Click "Generate new token (classic)"
42+
- Select the `read:packages` scope
43+
- Generate and copy the token
44+
45+
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):
46+
```shell
47+
export GITHUB_TOKEN=your_token_here
48+
```
49+
Replace `YOUR_TOKEN_HERE` with your actual token.
50+
51+
Install the extension package in editable mode. It installs the package’s dependencies, too:
52+
53+
```shell
54+
uv pip install --editable . --verbose
55+
```
56+
57+
Link your development version of the extension with JupyterLab:
58+
59+
```shell
60+
jupyter labextension develop . --overwrite
61+
```
62+
63+
Enable the extension in Jupyter Server:
64+
65+
```shell
66+
jupyter server extension enable jupyterlab_deepnote
67+
```
68+
69+
Rebuild the extension’s Typescript source after making changes:
70+
71+
```shell
72+
jlpm run watch
73+
```
74+
75+
The `jlpm` command is JupyterLab's pinned version of
76+
[yarn](https://yarnpkg.com/) that is installed with JupyterLab. You may use
77+
`yarn` or `npm` instead of `jlpm` below.
78+
79+
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.
80+
81+
```shell
82+
jupyter lab --debug
83+
```
84+
85+
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.
86+
87+
```bash
88+
# Watch the source directory in one terminal, automatically rebuilding when needed
89+
jlpm watch
90+
# Run JupyterLab in another terminal
91+
jupyter lab
92+
```
93+
94+
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).
95+
96+
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:
97+
98+
```bash
99+
jupyter lab build --minimize=False
100+
```
101+
102+
## Development uninstall
103+
104+
```bash
105+
# Server extension must be manually disabled in develop mode
106+
jupyter server extension disable jupyterlab_deepnote
107+
pip uninstall jupyterlab_deepnote
108+
```
109+
110+
In development mode, you will also need to remove the symlink created by `jupyter labextension develop`
111+
command. To find its location, you can run `jupyter labextension list` to figure out where the `labextensions`
112+
folder is located. Then you can remove the symlink named `jupyterlab-deepnote` within that folder.
113+
114+
## Testing the extension
115+
116+
### Server tests
117+
118+
This extension is using [Pytest](https://docs.pytest.org/) for Python code testing.
119+
120+
Install test dependencies (needed only once):
121+
122+
```sh
123+
pip install -e ".[test]"
124+
# Each time you install the Python package, you need to restore the front-end extension link
125+
jupyter labextension develop . --overwrite
126+
```
127+
128+
To execute them, run:
129+
130+
```sh
131+
pytest -vv -r ap --cov jupyterlab_deepnote
132+
```
133+
134+
### Frontend tests
135+
136+
This extension is using [Jest](https://jestjs.io/) for JavaScript code testing.
137+
138+
To execute them, execute:
139+
140+
```sh
141+
jlpm
142+
jlpm test
143+
```
144+
145+
## Versioning and compatibility
146+
147+
We follow [Semantic Versioning (semver)](https://semver.org/).
148+
149+
The extension pins JupyterLab to the current major version in both Python and JavaScript dependencies to ensure compatibility.
150+
151+
**Example `pyproject.toml` dependency:**
152+
153+
```toml
154+
[project.optional-dependencies]
155+
jupyterlab = ["jupyterlab>=4.0.0,<5.0.0"]
156+
```
157+
158+
**Example `package.json` peerDependencies:**
159+
160+
```json
161+
"peerDependencies": {
162+
"@jupyterlab/application": "^4.0.0",
163+
"@jupyterlab/apputils": "^4.0.0",
164+
"jupyterlab": "^4.0.0"
165+
}
166+
```
167+
168+
## Sync with the JupyterLab extension template
169+
170+
This project was bootstrapped using the [JupyterLab extension template](https://github.com/jupyterlab/extension-template). To keep your project up to date with improvements and best practices from the template, run:
171+
172+
```sh
173+
copier update --trust
174+
```
175+
176+
This will apply the latest template changes interactively. Review and commit any updates as appropriate.
177+
178+
## Release workflow
179+
180+
See [RELEASE](RELEASE.md) for details on the release process. We recommend using [Jupyter Releaser](https://github.com/jupyter-server/jupyter_releaser) and [PyPI trusted publishing](https://docs.pypi.org/trusted-publishers/) for secure and automated releases.

‎README.md‎

Lines changed: 18 additions & 153 deletions
Original file line numberDiff line numberDiff line change
@@ -3,188 +3,53 @@
33
[![CI](https://github.com/deepnote/jupyterlab-deepnote/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/deepnote/jupyterlab-deepnote/actions/workflows/ci.yml)
44
[![codecov](https://codecov.io/gh/deepnote/jupyterlab-deepnote/graph/badge.svg?token=OV32VZNOJ2)](https://codecov.io/gh/deepnote/jupyterlab-deepnote)
55

6-
A Deepnote extension for JupyterLab
7-
8-
This extension is composed of a Python package named `jupyterlab_deepnote`
9-
for the server extension and a NPM package named `jupyterlab-deepnote`
10-
for the frontend extension.
6+
Read‑only viewer for Deepnote `.deepnote` files inside JupyterLab.
117

128
## Requirements
139

14-
- JupyterLab >= 4.0.0
10+
- Python 3.9 or higher
11+
- JupyterLab 4.5.0 or higher
1512

1613
## Install
1714

18-
To install the extension:
15+
Install the extension using pip:
1916

2017
```bash
2118
pip install jupyterlab_deepnote
2219
```
2320

24-
## Uninstall
21+
## Usage
2522

26-
To remove the extension, execute:
23+
After installation you can:
2724

28-
```bash
29-
pip uninstall jupyterlab_deepnote
30-
```
25+
- Open Deepnote files (`.deepnote`) containing Deepnote projects in JupyterLab
26+
- Switch between notebooks inside a `.deepnote` file
27+
- View content in **read‑only** mode (no editing or saving back to the `.deepnote` file)
3128

32-
## Troubleshoot
29+
## Troubleshooting
3330

34-
If you are seeing the frontend extension, but it is not working, check
35-
that the server extension is enabled:
31+
If you encounter issues with the extension, verify that both the server and frontend extensions are properly installed and enabled.
32+
33+
Check server extensions:
3634

3735
```bash
3836
jupyter server extension list
3937
```
4038

41-
If the server extension is installed and enabled, but you are not seeing
42-
the frontend extension, check the frontend extension is installed:
39+
Check frontend extensions:
4340

4441
```bash
4542
jupyter labextension list
4643
```
4744

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-
```
45+
## Uninstall
14446

145-
### Development uninstall
47+
To remove the extension, run:
14648

14749
```bash
148-
# Server extension must be manually disabled in develop mode
149-
jupyter server extension disable jupyterlab_deepnote
15050
pip uninstall jupyterlab_deepnote
15151
```
15252

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
53+
## Contributing
18954

190-
See [RELEASE](RELEASE.md)
55+
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute to this project.

0 commit comments

Comments
 (0)