Add a devcontainer

.devcontainer/Dockerfile

@@ -0,0 +1,21 @@
+# See here for image contents: https://github.com/microsoft/vscode-dev-containers/tree/v0.245.2/containers/python-3/.devcontainer/base.Dockerfile
+
+# [Choice] Python version (use -bullseye variants on local arm64/Apple Silicon): 3, 3.10, 3.9, 3.8, 3.7, 3.6, 3-bullseye, 3.10-bullseye, 3.9-bullseye, 3.8-bullseye, 3.7-bullseye, 3.6-bullseye, 3-buster, 3.10-buster, 3.9-buster, 3.8-buster, 3.7-buster, 3.6-buster
+ARG VARIANT="3.10-bullseye"
+FROM mcr.microsoft.com/vscode/devcontainers/python:0-${VARIANT}
+
+# [Choice] Node.js version: none, lts/*, 16, 14, 12, 10
+ARG NODE_VERSION="none"
+RUN if [ "${NODE_VERSION}" != "none" ]; then su vscode -c "umask 0002 && . /usr/local/share/nvm/nvm.sh && nvm install ${NODE_VERSION} 2>&1"; fi
+
+# [Optional] If your pip requirements rarely change, uncomment this section to add them to the image.
+# COPY requirements.txt /tmp/pip-tmp/
+# RUN pip3 --disable-pip-version-check --no-cache-dir install -r /tmp/pip-tmp/requirements.txt \
+#    && rm -rf /tmp/pip-tmp
+
+# [Optional] Uncomment this section to install additional OS packages.
+# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
+#     && apt-get -y install --no-install-recommends <your-package-list-here>
+
+# [Optional] Uncomment this line to install global node packages.
+# RUN su vscode -c "source /usr/local/share/nvm/nvm.sh && npm install -g <your-package-here>" 2>&1

.devcontainer/devcontainer.json

@@ -0,0 +1,54 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
+// https://github.com/microsoft/vscode-dev-containers/tree/v0.245.2/containers/python-3
+{
+	"name": "Python 3",
+	"build": {
+		"dockerfile": "Dockerfile",
+		"context": "..",
+		"args": {
+			// Update 'VARIANT' to pick a Python version: 3, 3.10, 3.9, 3.8, 3.7, 3.6
+			// Append -bullseye or -buster to pin to an OS version.
+			// Use -bullseye variants on local on arm64/Apple Silicon.
+			"VARIANT": "3.10",
+			// Options
+			"NODE_VERSION": "14"
+		}
+	},
+	// Configure tool-specific properties.
+	"customizations": {
+		// Configure properties specific to VS Code.
+		"vscode": {
+			// Set *default* container specific settings.json values on container create.
+			"settings": {
+				"python.defaultInterpreterPath": "/usr/local/bin/python",
+				"python.linting.enabled": true,
+				"python.linting.pylintEnabled": true,
+				"python.formatting.autopep8Path": "/usr/local/py-utils/bin/autopep8",
+				"python.formatting.blackPath": "/usr/local/py-utils/bin/black",
+				"python.formatting.yapfPath": "/usr/local/py-utils/bin/yapf",
+				"python.linting.banditPath": "/usr/local/py-utils/bin/bandit",
+				"python.linting.flake8Path": "/usr/local/py-utils/bin/flake8",
+				"python.linting.mypyPath": "/usr/local/py-utils/bin/mypy",
+				"python.linting.pycodestylePath": "/usr/local/py-utils/bin/pycodestyle",
+				"python.linting.pydocstylePath": "/usr/local/py-utils/bin/pydocstyle",
+				"python.linting.pylintPath": "/usr/local/py-utils/bin/pylint"
+			},
+			// Add the IDs of extensions you want installed when the container is created.
+			"extensions": [
+				"ms-python.python",
+				"ms-python.vscode-pylance"
+			]
+		}
+	},
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+	// Use 'postCreateCommand' to run commands after the container is created.
+	"postCreateCommand": "./.devcontainer/scripts/setup.sh",
+	// Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
+	"remoteUser": "vscode",
+	"features": {
+		"git": "latest",
+		"github-cli": "latest",
+		"jupyterlab": "latest"
+	}
+}

.devcontainer/scripts/setup.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+pip install -e .
+python setup.py build
+
+# sudo mkdir /usr/local/share/jupyter
+# sudo chown vscode /usr/local/share/jupyter
+# jupyter labextension develop . --overwrite --no-build
+jupyter server extension enable nbdime # if developing for jupyter lab or nbclassic
+jupyter labextension develop . --overwrite

.gitignore

@@ -15,7 +15,6 @@ MANIFEST
 
 
 .spyderproject
-**/.vscode/
 **/node_modules/
 nbdime/webapp/test/build/
 nbdime/webapp/build/

.vscode/launch.json

@@ -0,0 +1,17 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug Jest Tests",
+      "type": "node",
+      "request": "launch",
+      "runtimeArgs": [
+        "--inspect-brk",
+        "${workspaceRoot}/node_modules/.bin/jest",
+        "--runInBand"
+      ],
+      "console": "integratedTerminal",
+      "internalConsoleOptions": "neverOpen"
+    }
+  ]
+}

.vscode/scripts/rebuild-lab.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+npm run build
+cd /packages/labextension
+npm run build:dev

.vscode/scripts/run-webapp.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+head="${1:-./nbdime/tests/files/apap--1.ipynb}"
+base="${2:-./nbdime/tests/files/apap.ipynb}"
+python -m nbdime diff-web $head $base

.vscode/scripts/watch-lab.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+
+watch_lab() {
+	cd packages/labextension
+	npm run watch
+}
+
+watch_ndime() {
+	cd packages/nbdime
+	npm run watch
+}
+
+watch_lab & watch_ndime & jupyter lab --watch

.vscode/scripts/watch-webapp.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+
+watch_ndime() {
+	cd packages/nbdime
+	npm run watch
+}
+
+watch_webapp() {
+	cd packages/webapp
+	npm run watch
+}
+
+watch_ndime & watch_webapp

.vscode/tasks.json

@@ -0,0 +1,86 @@
+{
+	"tasks": [
+		{
+			"type": "npm",
+			"script": "build",
+			"group": "build",
+			"problemMatcher": [],
+			"label": "npm: build",
+			"detail": "lerna run build"
+		},
+		{
+			"type": "shell",
+			"command": "./.vscode/scripts/rebuild-lab.sh",
+			"group": "build",
+			"problemMatcher": [],
+			"label": "rebuild-lab",
+			"detail": "rebuild lab"
+		},
+		{
+			"type": "shell",
+			"command": "./.vscode/scripts/watch-lab.sh",
+			"group": "build",
+			"problemMatcher": [],
+			"label": "watch-lab",
+			"detail": "watch lab",
+			"presentation": {
+				"panel": "dedicated"
+			}
+		},
+		{
+			"type": "shell",
+			"command": "./.vscode/scripts/watch-webapp.sh",
+			"group": "build",
+			"problemMatcher": [],
+			"label": "watch-webapp",
+			"detail": "watch webapp",
+			"presentation": {
+				"panel": "dedicated"
+			}
+		},
+		{
+			"type": "shell",
+			"command": "jupyter lab",
+			"group": "build",
+			"problemMatcher": [],
+			"label": "Run Jupyter Lab",
+			"detail": "Run Jupyter Lab",
+			"presentation": {
+				"panel": "dedicated"
+			}
+		},
+		{
+			"type": "shell",
+			"command": "./.vscode/scripts/run-webapp.sh",
+			"group": "build",
+			"problemMatcher": [],
+			"label": "run-webapp",
+			"detail": "run webapp",
+			"presentation": {
+				"panel": "dedicated"
+			},
+			"inputs": [
+				{
+					"id": "head",
+					"description": "Head Notebook:",
+					"default": "./nbdime/tests/files/apap--1.ipynb",
+					"type": "promptString"
+				},
+				{
+					"id": "base",
+					"description": "Base Notebook:",
+					"default": "./nbdime/tests/files/apap.ipynb",
+					"type": "promptString"
+				}
+			]
+		},
+		{
+			"type": "npm",
+			"script": "test",
+			"group": "test",
+			"problemMatcher": [],
+			"label": "npm: test",
+			"detail": "lerna run test"
+		}
+	]
+}

CONTRIBUTING.md

@@ -1,3 +1,27 @@
 # Contributing
 
 We follow the [IPython Contributing Guide](https://github.com/ipython/ipython/blob/master/CONTRIBUTING.md).
+
+# Contributing with codespaces
+
+Opening this repository in Codespaces will pre-install the environment you need to develop with.
+
+## Updating Javascript packages.
+
+This project uses lerna to manage the multiple packages inside the packages folder. If you run an npm command at the root it will run the command for each subpackage. This is good for working across packages, however more commonly we want to work with an individual package. To do this change directories into the package you wish to alter, then npm will run only for that package.
+
+### Adding npm dependency
+
+This should be done inside the directory of the package which requires the dependency.
+
+### Testing changes to the webapp
+
+The python setup.py script will built the entirety of the project and place it inside the build folder. Run `python setup.py build` once you are ready to test a change. Then the nbdime module can be invoked to test changes by running `python -m nbdime service` for example diff web can be started at `python -m nbdime diff-web testnotebookpath testnotebookpath2` there are test notebooks in the `nbdime/webapp/testnotebook` folder.
+
+### Running npm tests
+
+The project uses jest to test the javascript, a typescript compile step occurs before the test suite runs. You can run the tests for the entire project with `npm run test` in the root, or change directories to the package you are working on and run `npm run test` to test just that package.
+
+### VSCode/CodeSpace Setup
+
+If you are working in vscode with GitHub codespaces many of the command you will need to run have been moved into vscode tasks. This includes building the webapp and lab extension, running test, launching the webapp, launching vscode and others. You can see the available tasks by choosing `Run Build Task from the global Terminal menu` to learn more about tasks see [this doc](https://code.visualstudio.com/docs/editor/tasks).