From 1efc8892dbf8bdfa8c4440744305d86756f92f9f Mon Sep 17 00:00:00 2001 From: Andy Jakubowski Date: Thu, 16 Oct 2025 15:36:37 +0200 Subject: [PATCH 1/7] Add CONTRIBUTING.md Signed-off-by: Andy Jakubowski --- CONTRIBUTING.md | 143 +++++++++++++++++++++++++++++++++++++++++++++++ README.md | 144 ------------------------------------------------ 2 files changed, 143 insertions(+), 144 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..3c5313d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,143 @@ +# Contributing to `jupyterlab-deepnote` + +## Development install + +Note: You will need NodeJS to build the extension package. + +Use any Python environment and dependency manager you like, for example [uv](https://docs.astral.sh/uv/getting-started/installation/): + +```shell +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +Create a Python environment in the project directory: + +```shell +uv venv --python 3.12 --managed-python +``` + +Activate the Python environment: + +```shell +source .venv/bin/activate +``` + +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. + +```shell +uv pip install jupyterlab +``` + +**Configure Access to @deepnote/blocks Package** + +The `@deepnote/blocks` package is published on GitHub Packages. To install it, you'll need to authenticate with GitHub: + +1. Create a GitHub Personal Access Token (classic) with `read:packages` scope: + - Go to https://github.com/settings/tokens + - Click "Generate new token (classic)" + - Select the `read:packages` scope + - Generate and copy the token + +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): + ```shell + export GITHUB_TOKEN=your_token_here + ``` + Replace `YOUR_TOKEN_HERE` with your actual token. + +Install the extension package in editable mode. It installs the package’s dependencies, too: + +```shell +uv pip install --editable . --verbose +``` + +Link your development version of the extension with JupyterLab: + +```shell +jupyter labextension develop . --overwrite +``` + +Enable the extension in Jupyter Server: + +```shell +jupyter server extension enable jupyterlab_deepnote +``` + +Rebuild the extension’s Typescript source after making changes: + +```shell +jlpm run watch +``` + +The `jlpm` command is JupyterLab's pinned version of +[yarn](https://yarnpkg.com/) that is installed with JupyterLab. You may use +`yarn` or `npm` instead of `jlpm` below. + +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. + +```shell +jupyter lab --debug +``` + +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. + +```bash +# Watch the source directory in one terminal, automatically rebuilding when needed +jlpm watch +# Run JupyterLab in another terminal +jupyter lab +``` + +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). + +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: + +```bash +jupyter lab build --minimize=False +``` + +## Development uninstall + +```bash +# Server extension must be manually disabled in develop mode +jupyter server extension disable jupyterlab_deepnote +pip uninstall jupyterlab_deepnote +``` + +In development mode, you will also need to remove the symlink created by `jupyter labextension develop` +command. To find its location, you can run `jupyter labextension list` to figure out where the `labextensions` +folder is located. Then you can remove the symlink named `jupyterlab-deepnote` within that folder. + +## Testing the extension + +### Server tests + +This extension is using [Pytest](https://docs.pytest.org/) for Python code testing. + +Install test dependencies (needed only once): + +```sh +pip install -e ".[test]" +# Each time you install the Python package, you need to restore the front-end extension link +jupyter labextension develop . --overwrite +``` + +To execute them, run: + +```sh +pytest -vv -r ap --cov jupyterlab_deepnote +``` + +### Frontend tests + +This extension is using [Jest](https://jestjs.io/) for JavaScript code testing. + +To execute them, execute: + +```sh +jlpm +jlpm test +``` + +## Packaging the extension + +See [RELEASE](RELEASE.md) diff --git a/README.md b/README.md index 16ec71d..dc0bcaa 100644 --- a/README.md +++ b/README.md @@ -44,147 +44,3 @@ the frontend extension, check the frontend extension is installed: ```bash jupyter labextension list ``` - -## Contributing - -### Development install - -Note: You will need NodeJS to build the extension package. - -Use any Python environment and dependency manager you like, for example [uv](https://docs.astral.sh/uv/getting-started/installation/): - -```shell -curl -LsSf https://astral.sh/uv/install.sh | sh -``` - -Create a Python environment in the project directory: - -```shell -uv venv --python 3.12 --managed-python -``` - -Activate the Python environment: - -```shell -source .venv/bin/activate -``` - -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. - -```shell -uv pip install jupyterlab -``` - -**Configure Access to @deepnote/blocks Package** - -The `@deepnote/blocks` package is published on GitHub Packages. To install it, you'll need to authenticate with GitHub: - -1. Create a GitHub Personal Access Token (classic) with `read:packages` scope: - - Go to https://github.com/settings/tokens - - Click "Generate new token (classic)" - - Select the `read:packages` scope - - Generate and copy the token - -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): - ```shell - export GITHUB_TOKEN=your_token_here - ``` - Replace `YOUR_TOKEN_HERE` with your actual token. - -Install the extension package in editable mode. It installs the package’s dependencies, too: - -```shell -uv pip install --editable . --verbose -``` - -Link your development version of the extension with JupyterLab: - -```shell -jupyter labextension develop . --overwrite -``` - -Enable the extension in Jupyter Server: - -```shell -jupyter server extension enable jupyterlab_deepnote -``` - -Rebuild the extension’s Typescript source after making changes: - -```shell -jlpm run watch -``` - -The `jlpm` command is JupyterLab's pinned version of -[yarn](https://yarnpkg.com/) that is installed with JupyterLab. You may use -`yarn` or `npm` instead of `jlpm` below. - -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. - -```shell -jupyter lab --debug -``` - -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. - -```bash -# Watch the source directory in one terminal, automatically rebuilding when needed -jlpm watch -# Run JupyterLab in another terminal -jupyter lab -``` - -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). - -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: - -```bash -jupyter lab build --minimize=False -``` - -### Development uninstall - -```bash -# Server extension must be manually disabled in develop mode -jupyter server extension disable jupyterlab_deepnote -pip uninstall jupyterlab_deepnote -``` - -In development mode, you will also need to remove the symlink created by `jupyter labextension develop` -command. To find its location, you can run `jupyter labextension list` to figure out where the `labextensions` -folder is located. Then you can remove the symlink named `jupyterlab-deepnote` within that folder. - -### Testing the extension - -#### Server tests - -This extension is using [Pytest](https://docs.pytest.org/) for Python code testing. - -Install test dependencies (needed only once): - -```sh -pip install -e ".[test]" -# Each time you install the Python package, you need to restore the front-end extension link -jupyter labextension develop . --overwrite -``` - -To execute them, run: - -```sh -pytest -vv -r ap --cov jupyterlab_deepnote -``` - -#### Frontend tests - -This extension is using [Jest](https://jestjs.io/) for JavaScript code testing. - -To execute them, execute: - -```sh -jlpm -jlpm test -``` - -### Packaging the extension - -See [RELEASE](RELEASE.md) From e34145a1855eaa29fab972261ab838b088b1b20f Mon Sep 17 00:00:00 2001 From: Andy Jakubowski Date: Thu, 16 Oct 2025 17:04:42 +0200 Subject: [PATCH 2/7] docs: update README, CONTRIBUTING, RELEASE Signed-off-by: Andy Jakubowski --- CONTRIBUTING.md | 41 +++++++++++++++++++++++++++++++++++++++-- README.md | 47 ++++++++++++++++++++++++++++++----------------- RELEASE.md | 9 ++------- 3 files changed, 71 insertions(+), 26 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3c5313d..b75918a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,7 @@ +# Scope + +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. + # Contributing to `jupyterlab-deepnote` ## Development install @@ -138,6 +142,39 @@ jlpm jlpm test ``` -## Packaging the extension +## Versioning and compatibility + +We follow [Semantic Versioning (semver)](https://semver.org/). + +The extension pins JupyterLab to the current major version in both Python and JavaScript dependencies to ensure compatibility. + +**Example `pyproject.toml` dependency:** + +```toml +[project.optional-dependencies] +jupyterlab = ["jupyterlab>=4.0.0,<5.0.0"] +``` + +**Example `package.json` peerDependencies:** + +```json + "peerDependencies": { + "@jupyterlab/application": "^4.0.0", + "@jupyterlab/apputils": "^4.0.0", + "jupyterlab": "^4.0.0" + } +``` + +## Sync with the JupyterLab extension template + +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: + +```sh +copier update --trust +``` + +This will apply the latest template changes interactively. Review and commit any updates as appropriate. + +## Release workflow -See [RELEASE](RELEASE.md) +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. diff --git a/README.md b/README.md index dc0bcaa..c0c5cf0 100644 --- a/README.md +++ b/README.md @@ -3,44 +3,57 @@ [![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) [![codecov](https://codecov.io/gh/deepnote/jupyterlab-deepnote/graph/badge.svg?token=OV32VZNOJ2)](https://codecov.io/gh/deepnote/jupyterlab-deepnote) -A Deepnote extension for JupyterLab - -This extension is composed of a Python package named `jupyterlab_deepnote` -for the server extension and a NPM package named `jupyterlab-deepnote` -for the frontend extension. +Read‑only viewer for Deepnote `.deepnote` files inside JupyterLab. ## Requirements -- JupyterLab >= 4.0.0 +- Python 3.7 or higher +- JupyterLab 4.0.0 or higher ## Install -To install the extension: +Install the extension using pip: ```bash pip install jupyterlab_deepnote ``` -## Uninstall +## Usage -To remove the extension, execute: +After installation you can: -```bash -pip uninstall jupyterlab_deepnote -``` +- Open Deepnote files (`.deepnote`) containing Deepnote projects in JupyterLab +- Switch between notebooks inside a `.deepnote` file +- View content in **read‑only** mode (no editing or saving back to the `.deepnote` file) -## Troubleshoot +## Compatibility and Maintenance -If you are seeing the frontend extension, but it is not working, check -that the server extension is enabled: +This extension is maintained to be compatible with JupyterLab versions 4.x. It is recommended to keep your JupyterLab installation updated within this major version to ensure full compatibility. + +## Troubleshooting + +If you encounter issues with the extension, verify that both the server and frontend extensions are properly installed and enabled. + +Check server extensions: ```bash jupyter server extension list ``` -If the server extension is installed and enabled, but you are not seeing -the frontend extension, check the frontend extension is installed: +Check frontend extensions: ```bash jupyter labextension list ``` + +## Uninstall + +To remove the extension, run: + +```bash +pip uninstall jupyterlab_deepnote +``` + +## Contributing + +Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute to this project. diff --git a/RELEASE.md b/RELEASE.md index 37aa46a..a0eadc1 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -1,6 +1,6 @@ # Making a new release of jupyterlab_deepnote -The extension can be published to `PyPI` and `npm` manually or using the [Jupyter Releaser](https://github.com/jupyter-server/jupyter_releaser). +This extension requires both a frontend and backend component to function properly. Therefore, we only publish the Python package to `PyPI`. The NPM package alone would not do anything and is not published separately. ## Manual release @@ -49,12 +49,7 @@ twine upload dist/* ### NPM package -To publish the frontend part of the extension as a NPM package, do: - -```bash -npm login -npm publish --access public -``` +The frontend part of this extension is not published separately as an NPM package because it requires the backend component to function. Publishing only the NPM package would not provide a working extension. ## Automated releases with the Jupyter Releaser From f1210d22c7f4d3d90e81e438e7699931e42e0140 Mon Sep 17 00:00:00 2001 From: Andy Jakubowski Date: Thu, 16 Oct 2025 17:06:22 +0200 Subject: [PATCH 3/7] Fix heading Signed-off-by: Andy Jakubowski --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b75918a..a63079d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -32,7 +32,7 @@ Install `jupyterlab`. The extension package itself doesn’t depend on `jupyterl uv pip install jupyterlab ``` -**Configure Access to @deepnote/blocks Package** +### Configure Access to @deepnote/blocks Package The `@deepnote/blocks` package is published on GitHub Packages. To install it, you'll need to authenticate with GitHub: From cce9f5647f9e0ae7982d4e8c7360b6731f2bd3d5 Mon Sep 17 00:00:00 2001 From: Andy Jakubowski Date: Fri, 17 Oct 2025 09:21:42 +0200 Subject: [PATCH 4/7] Update Python version Signed-off-by: Andy Jakubowski --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c0c5cf0..61f3a7c 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ Read‑only viewer for Deepnote `.deepnote` files inside JupyterLab. ## Requirements -- Python 3.7 or higher +- Python 3.9 or higher - JupyterLab 4.0.0 or higher ## Install From fd857e123b9fd661b1edb3888b03a8c84a85c3b9 Mon Sep 17 00:00:00 2001 From: Andy Jakubowski Date: Fri, 17 Oct 2025 09:48:42 +0200 Subject: [PATCH 5/7] Update readme Signed-off-by: Andy Jakubowski --- README.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/README.md b/README.md index 61f3a7c..bf50264 100644 --- a/README.md +++ b/README.md @@ -26,10 +26,6 @@ After installation you can: - Switch between notebooks inside a `.deepnote` file - View content in **read‑only** mode (no editing or saving back to the `.deepnote` file) -## Compatibility and Maintenance - -This extension is maintained to be compatible with JupyterLab versions 4.x. It is recommended to keep your JupyterLab installation updated within this major version to ensure full compatibility. - ## Troubleshooting If you encounter issues with the extension, verify that both the server and frontend extensions are properly installed and enabled. From deefc6757bdf71fa9540526e6ca71eaea9025716 Mon Sep 17 00:00:00 2001 From: Andy Jakubowski Date: Fri, 17 Oct 2025 10:30:34 +0200 Subject: [PATCH 6/7] Remove conda forge release instructions Conda should not be a recommended package registry target Signed-off-by: Andy Jakubowski --- RELEASE.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index a0eadc1..090757c 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -67,9 +67,3 @@ Here is a summary of the steps to cut a new release: > [!NOTE] > Check out the [workflow documentation](https://jupyter-releaser.readthedocs.io/en/latest/get_started/making_release_from_repo.html) > for more information. - -## Publishing to `conda-forge` - -If the package is not on conda forge yet, check the documentation to learn how to add it: https://conda-forge.org/docs/maintainer/adding_pkgs.html - -Otherwise a bot should pick up the new version publish to PyPI, and open a new PR on the feedstock repository automatically. From c700cdc532307f14cfee81b5772270a8ceaa3555 Mon Sep 17 00:00:00 2001 From: Andy Jakubowski Date: Fri, 17 Oct 2025 11:11:52 +0200 Subject: [PATCH 7/7] 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 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index bf50264..c4706d2 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Read‑only viewer for Deepnote `.deepnote` files inside JupyterLab. ## Requirements - Python 3.9 or higher -- JupyterLab 4.0.0 or higher +- JupyterLab 4.5.0 or higher ## Install