deepnote · jamesbhobbs · Oct 23, 2025 · Oct 16, 2025 · Oct 16, 2025 · Oct 16, 2025
@@ -0,0 +1,180 @@
+# 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
+
+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
+```
+
+## 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) 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.
@@ -3,188 +3,53 @@
 [![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.9 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
+## Troubleshooting
 
-If you are seeing the frontend extension, but it is not working, check
-that the server extension is enabled:
+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
 ```
 
-## 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
-```
+## Uninstall
 
-### Development uninstall
+To remove the extension, run:
 
 ```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
+## Contributing
 
-See [RELEASE](RELEASE.md)
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute to this project.