[WIP] update to modern JupyterLab

Author: afshin

.eslintignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+coverage
+**/*.d.ts
+tests

.eslintrc.js

@@ -0,0 +1,28 @@
+module.exports = {
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/eslint-recommended',
+    'plugin:@typescript-eslint/recommended',
+    'plugin:prettier/recommended'
+  ],
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    project: 'tsconfig.eslint.json',
+    sourceType: 'module'
+  },
+  plugins: ['@typescript-eslint'],
+  rules: {
+    '@typescript-eslint/no-unused-vars': ['warn', { args: 'none' }],
+    '@typescript-eslint/no-explicit-any': 'off',
+    '@typescript-eslint/no-namespace': 'off',
+    '@typescript-eslint/no-use-before-define': 'off',
+    '@typescript-eslint/quotes': [
+      'error',
+      'single',
+      { avoidEscape: true, allowTemplateLiterals: false }
+    ],
+    curly: ['error', 'all'],
+    eqeqeq: 'error',
+    'prefer-arrow-callback': 'error'
+  }
+};

.github/workflows/build.yml

@@ -0,0 +1,44 @@
+name: Build
+
+on:
+  push:
+    branches: main
+  pull_request:
+    branches: "*"
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.7", "3.10"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - uses: jupyterlab/maintainer-tools/.github/actions/base-setup@v1
+
+      - name: Install dependencies
+        run: |
+          python -m pip install -U codecov
+          npm install -g codecov
+      - name: Test the extension
+        run: |
+          python -m pip install --upgrade -v -e ".[test, examples, docs]"
+          python -m pytest
+          yarn run test
+
+      - name: Linting
+        if: ${{ matrix.os == 'ubuntu-latest' }}
+        run: |
+          yarn run lint:check
+
+      - name: Check docs can be build + links
+        if: ${{ matrix.os == 'ubuntu-latest' }}
+        working-directory: docs
+        run: |
+          sudo apt install -y pandoc
+          make html
+          python -m pytest --check-links

.gitignore

@@ -23,7 +23,6 @@ var/
 *.egg-info/
 .installed.cfg
 *.egg
-MANIFEST
 
 # PyInstaller
 #  Usually these files are written by a python script from a template
@@ -146,14 +145,11 @@ $RECYCLE.BIN/
 # ----
 
 **/node_modules/
-ipymidicontrols/nbextension/static/index.*
-ipymidicontrols/labextension/*.tgz
+ipymidicontrols/nbextension/index.*
 
 # Coverage data
 # -------------
 **/coverage/
 
 # Packed lab extensions
 ipymidicontrols/labextension
-
-tsconfig.tsbuildinfo

.prettierignore

@@ -0,0 +1,4 @@
+node_modules
+**/node_modules
+**/lib
+**/package.json

.prettierrc

@@ -0,0 +1,3 @@
+{
+    "singleQuote": true
+}

.travis.yml

@@ -1,4 +1,4 @@
-Copyright (c) 2018 Project Jupyter Contributors
+Copyright (c) 2023 Project Jupyter Contributors
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

LICENSE.txt

@@ -1,12 +1,14 @@
 include LICENSE.txt
 include README.md
 
-include setupbase.py
-# include pytest.ini
-# include .coveragerc
+include setup.py
+include pyproject.toml
+include pytest.ini
+include .coverage.rc
 
-# include package.json
-# include webpack.config.js
+include tsconfig.json
+include package.json
+include webpack.config.js
 include ipymidicontrols/labextension/*.tgz
 
 # Documentation
@@ -20,12 +22,13 @@ prune docs/dist
 graft examples
 
 # Tests
-# graft tests
-# prune tests/build
+graft tests
+prune tests/build
 
 # Javascript files
 graft ipymidicontrols/nbextension
-# graft src
+graft src
+graft css
 prune **/node_modules
 prune coverage
 prune lib

MANIFEST.in

@@ -15,33 +15,69 @@ You can install using `pip`:
 pip install ipymidicontrols
 ```
 
-Or if you use jupyterlab:
+If you are using Jupyter Notebook 5.2 or earlier, you may also need to enable
+the nbextension:
+```bash
+jupyter nbextension enable --py [--sys-prefix|--user|--system] ipymidicontrols
+```
+
+## Development Installation
 
+Create a dev environment:
 ```bash
-pip install ipymidicontrols
-jupyter labextension install @jupyter-widgets/jupyterlab-manager
+conda create -n ipymidicontrols-dev -c conda-forge nodejs yarn python jupyterlab
+conda activate ipymidicontrols-dev
 ```
 
-If you are using Jupyter Notebook 5.2 or earlier, you may also need to enable
-the nbextension:
+Install the python. This will also build the TS package.
 ```bash
-jupyter nbextension enable --py [--sys-prefix|--user|--system] ipymidicontrols
+pip install -e ".[test, examples]"
 ```
 
-## Usage
+When developing your extensions, you need to manually enable your extensions with the
+notebook / lab frontend. For lab, this is done by the command:
 
-Create a controller widget for a [Behringer XTouch Mini](https://www.musictribe.com/Categories/Behringer/Computer-Audio/Desktop-Controllers/X-TOUCH-MINI/p/P0B3M):
+```
+jupyter labextension develop --overwrite .
+yarn run build
+```
 
-```python
-from ipymidicontrols import XTouchMini
-x = XTouchMini()
+For classic notebook, you need to run:
+
+```
+jupyter nbextension install --sys-prefix --symlink --overwrite --py ipymidicontrols
+jupyter nbextension enable --sys-prefix --py ipymidicontrols
 ```
 
-See a simple widgets-based UI for the controls:
+Note that the `--symlink` flag doesn't work on Windows, so you will here have to run
+the `install` command every time that you rebuild your extension. For certain installations
+you might also need another flag instead of `--sys-prefix`, but we won't cover the meaning
+of those flags here.
+
+### How to see your changes
+#### Typescript:
+If you use JupyterLab to develop then 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 widget.
+
+```bash
+# Watch the source directory in one terminal, automatically rebuilding when needed
+yarn run watch
+# Run JupyterLab in another terminal
+jupyter lab
+```
 
-```python
-from ipymidicontrols import xtouchmini_ui
-xtouchmini_ui(x)
+After a change wait for the build to finish and then refresh your browser and the changes should take effect.
+
+#### Python:
+If you make a change to the python code then you will need to restart the notebook kernel to have it take effect.
+
+## Updating the version
+
+To update the version, install tbump and use it to bump the version.
+By default it will also create a tag.
+
+```bash
+pip install tbump
+tbump <new-version>
 ```
 
-![screenshot](https://raw.githubusercontent.com/jupyter-widgets/midicontrols/master/XTouchMini.png)