Migrate to prebuilt extension to support JupyterLab v3.x

.eslintignore

@@ -1,3 +1,4 @@
 **/*.d.ts
-tests
+coverage
+dist
 lib

.github/workflows/build.yml

@@ -2,45 +2,49 @@ name: Build
 
 on:
   push:
-    branches: main
+    branches:
+      - main
   pull_request:
-    branches: '*'
+    branches:
+      - main
 
 jobs:
   build:
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        jupyterlab: ['2.0', '3.0.0']
-      fail-fast: false
     steps:
-      - name: Checkout
+      - name: Checkout 🏷️
         uses: actions/checkout@v2
 
-      - name: Install node
+      - name: Use Node 14 🕹️
         uses: actions/setup-node@v2
         with:
-          node-version: '12.x'
+          node-version: '14.x'
 
-      - name: Install Python
+      - name: Install Python 🐍
         uses: actions/setup-python@v2
         with:
           python-version: '3.6'
           architecture: 'x64'
 
-      - name: Install dependencies
-        run: python -m pip install jupyterlab~=${{ matrix.jupyterlab }}
+      - name: Install dependencies ⚙️
+        run: python -m pip install -U jupyterlab~=3.0 check-manifest
 
-      - name: Build the extension
+      - name: Build the extension 🏗️
         run: |
+          set -eux
           jlpm
           jlpm run lint
+          python -m pip install .
 
-          pip install .
-          jupyter lab build
-          jupyter serverextension list 1>serverextensions 2>&1
-          cat serverextensions | grep "jupyterlab_h5web.*OK"
-          jupyter labextension list 1>labextensions 2>&1
-          cat labextensions | grep "jupyterlab-h5web.*OK"
+          jupyter serverextension list 2>&1 | grep -ie "jupyterlab_h5web.*OK"
+          jupyter labextension list 2>&1 | grep -ie "jupyterlab-h5web.*OK"
 
           python -m jupyterlab.browser_check
+
+          check-manifest -v
+
+          pip install build
+          python -m build --sdist
+          cp dist/*.tar.gz jupyterlab_h5web.tar.gz
+          pip uninstall -y jupyterlab_h5web jupyterlab
+          rm -rf jupyterlab_h5web

.github/workflows/legacy_build.yml

@@ -0,0 +1,43 @@
+name: Build for JupyterLab 2
+
+on:
+  push:
+    branches:
+      - 0.x
+  pull_request:
+    branches:
+      - 0.x
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout 🏷️
+        uses: actions/checkout@v2
+
+      - name: Use Node 14 🕹️
+        uses: actions/setup-node@v2
+        with:
+          node-version: '14.x'
+
+      - name: Install Python 🐍
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.6'
+          architecture: 'x64'
+
+      - name: Install dependencies ⚙️
+        run: python -m pip install -U jupyterlab~=2.0
+
+      - name: Build the extension 🏗️
+        run: |
+          set -eux
+          jlpm
+          jlpm run lint
+          python -m pip install .
+          jupyter lab build
+
+          jupyter serverextension list 2>&1 | grep -ie "jupyterlab_h5web.*OK"
+          jupyter labextension list 2>&1 | grep -ie "jupyterlab-h5web.*OK"
+
+          python -m jupyterlab.browser_check

.github/workflows/release.yml

@@ -17,10 +17,10 @@ jobs:
         env:
           TAG_PREFIX: refs/tags/v
 
-      - name: Use Node 12 🕹️
+      - name: Use Node 14 🕹️
         uses: actions/setup-node@v2
         with:
-          node-version: '12'
+          node-version: '14'
 
       - name: Install Python 🐍
         uses: actions/setup-python@v2

.gitignore

@@ -4,8 +4,8 @@ node_modules/
 *.egg-info/
 .ipynb_checkpoints
 *.tsbuildinfo
+jupyterlab_h5web/labextension
 
-*/labextension/*.tgz
 # Created by https://www.gitignore.io/api/python
 # Edit at https://www.gitignore.io/?templates=python
 

CONTRIBUTING.md

@@ -2,73 +2,70 @@
 
 ## Install
 
+Note: You will need NodeJS to build the extension package.
+
 The `jlpm` command is JupyterLab's pinned version of
 [yarn](https://yarnpkg.com/) that is installed with JupyterLab. You may use
 `yarn` or `npm` in lieu of `jlpm` below.
 
 ```bash
 # Clone the repo to your local environment
-# Move to jupyterlab-h5web directory
-
+# Change directory to the jupyterlab_h5web directory
 # Install package in development mode
 pip install -e .
-# Ensure that `jupyterlab_h5web` server extension is present and enabled
-jupyter serverextension list
-
-# Install dependencies
-jlpm
-# Build Typescript source
-jlpm build
 # Link your development version of the extension with JupyterLab
-jupyter labextension install .
-# Rebuild Typescript source after making changes
-jlpm build
-# Rebuild JupyterLab after making any changes
-jupyter lab build
+jupyter labextension develop . --overwrite
+# Server extension must be manually installed in develop mode
+jupyter server extension enable jupyterlab_h5web
+# Rebuild extension Typescript source after making changes
+jlpm run build
 ```
 
-You can watch the source directory and run JupyterLab in watch mode to watch for
-changes in the extension's source and automatically rebuild the extension and
-application.
+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 another terminal tab
-jlpm watch
-# Run jupyterlab in watch mode in one terminal tab
-jupyter lab --watch
+# Watch the source directory in one terminal, automatically rebuilding when needed
+jlpm run watch
+# Run JupyterLab in another terminal
+jupyter lab
 ```
 
-Now every change will be built locally and bundled into JupyterLab. Be sure to
-refresh your browser page after saving file changes to reload the extension
-(note: you'll need to wait for webpack to finish, which can take 10s+ at times).
-
-## Formatting
-
-This extension uses `prettier` to format `*.ts` files and `black` to format
-`*.py` files.
+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).
 
-## PyPI package
+By default, the `jlpm run 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:
 
-### Why a Python package for a front-end extension ?
+```bash
+jupyter lab build --minimize=False
+```
 
-1. To ease up installation
-2. To get ready to release a pre-built extension (_JupyterLab 3_)
+## Development uninstall
 
-The pre-built extension will indeed remove the need for `node`. For _JupyterLab
-2_, the extension must be included in JupyterLab at build. As a consequence, the
-PyPI package contains the TypeScript sources so that the installation of the
-PyPI package triggers a build of these sources (needing `node`).
+```bash
+# Server extension must be manually disabled in develop mode
+jupyter server extension disable jupyterlab_h5web
+pip uninstall jupyterlab_h5web
+```
 
-In _JupyterLab 3_, we will be able to pre-build the extension and release it as
-the PyPI package.
+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-h5web` within that
+folder.
 
-### Metadata
+## Formatting
 
-The metadata (author, licence, version...) is set in `package.json` that acts as
-a the single source of truth. The metadata of the PyPI package (`setup.py`) is
-fetched from `package.json`.
+This extension uses `prettier` to format `*.ts` files and `black` to format
+`*.py` files.
 
-### Release process
+## Release process
 
 The release process is adapted from
 [the one from h5web](https://github.com/silx-kit/h5web/blob/main/CONTRIBUTING.md#release-process).

MANIFEST.in

@@ -1,19 +1,24 @@
 include LICENSE.md
 include README.md
 include pyproject.toml
+exclude CONTRIBUTING.md
+exclude requirements_release.txt
+exclude example.ipynb
 
 include jupyter-config/jupyterlab-h5web.json
 
 include package.json
+include install.json
 include ts*.json
 include yarn.lock
-include jupyterlab_h5web/labextension/*.tgz
+graft jupyterlab_h5web/labextension
 
 # Javascript files
 graft src
 graft style
 prune **/node_modules
 prune lib
+prune binder
 
 # Patterns to exclude from any directory
 global-exclude *~

README.md

@@ -4,9 +4,6 @@
 [![PyPI version](https://badge.fury.io/py/jupyterlab-h5web.svg)](https://badge.fury.io/py/jupyterlab-h5web)
 [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/silx-kit/jupyterlab-h5web/HEAD?urlpath=lab/tree/example.ipynb)
 
-**This extension is still in active development. Please report any encountered
-issue.**
-
 ![Demo](https://user-images.githubusercontent.com/2936402/114533096-d5e68000-9c4d-11eb-81d3-67d313c9216f.gif)
 
 **jupyterlab-h5web** is a JupyterLab extension to explore and visualize HDF5
@@ -18,16 +15,16 @@ See [Usage](README.md#Usage) for more details.
 
 ## Requirements
 
-- JupyterLab 2 (JupyterLab 3 can be used up to 3.0.x but is not officially
-  supported).
+- JupyterLab 3
 
-## Install
+For JupyterLab 2, use the
+[0.x versions](https://github.com/silx-kit/jupyterlab-h5web/tree/0.x) of the
+extension.
 
-_Note: You will need NodeJS to install the extension._
+## Install
 
 ```bash
 pip install jupyterlab_h5web
-jupyter lab build
 ```
 
 To enable support for additional filters such as
@@ -36,29 +33,11 @@ To enable support for additional filters such as
 
 ```bash
 pip install jupyterlab_h5web[full]
-jupyter lab build
 ```
 
 This will install [hdf5plugin](https://pypi.org/project/hdf5plugin/) in addition
 to the extension.
 
-## Update
-
-In the case you want to update `jupyterlab_h5web` after having already installed
-it, do a clean reinstallation:
-
-```bash
-# Uninstall the old version
-jupyter labextension uninstall jupyterlab-h5web
-pip uninstall jupyterlab_h5web
-
-# Install the new version
-pip install jupyterlab_h5web
-jupyter lab build
-```
-
-Otherwise, the `labextension` may not be updated correctly.
-
 ## Usage
 
 This extension enables opening HDF5 files in a JupyterLab tab and exploring HDF5
@@ -110,6 +89,9 @@ See https://github.com/silx-kit/jupyterlab-h5web/releases.
 
 ## Troubleshoot
 
+If the following instructions do not solve your issue, you can open an
+[issue on GitHub](https://github.com/silx-kit/jupyterlab-h5web/issues).
+
 ### Check the server extension
 
 If you are seeing the frontend extension but it is not working, check that
@@ -136,22 +118,8 @@ frontend, check the frontend is installed:
 jupyter labextension list
 ```
 
-If it is installed, try:
-
-```bash
-jupyter lab clean
-jupyter lab build
-```
-
-### Stale H5Web
-
-In the case the displayed H5Web does not match the installed version, try to
-reinstall the package using the procedure described in
-[Update](README.md#Update).
-
 ## Uninstall
 
 ```bash
-jupyter labextension uninstall jupyterlab-h5web
 pip uninstall jupyterlab_h5web
 ```

binder/environment.yml

@@ -1,2 +1,2 @@
 dependencies:
-  - jupyterlab<3
+  - jupyterlab

example.ipynb

@@ -127,9 +127,9 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3 (jupyterlab2-h5web)",
+   "display_name": "Python 3",
    "language": "python",
-   "name": "jupyterlab2-h5web"
+   "name": "python3"
   },
   "language_info": {
    "codemirror_mode": {

install.json

@@ -0,0 +1,5 @@
+{
+  "packageManager": "python",
+  "packageName": "jupyterlab_h5web",
+  "uninstallInstructions": "Use your Python package manager (pip, conda, etc.) to uninstall the package jupyterlab_h5web"
+}