Merge pull request #913 from microsoft/jupyterServerProviderSample

Jupyter server provider sample

.scripts/samples.js

@@ -260,6 +260,13 @@ const samples = [
     apis: [],
     contributions: ["notebookRenderer"]
   },
+  {
+    description: 'jupyter-server-provider-sample',
+    path: 'jupyter-server-provider-sample',
+    guide: null,
+    apis: [],
+    contributions: []
+  },
   { description: 'configuration-sample', excludeFromReadme: true, path: 'configuration-sample', guide: null, apis: [], contributions: [] },
   { description: 'contentprovider-sample', excludeFromReadme: true, path: 'contentprovider-sample', guide: null, apis: [], contributions: [] },
   { description: 'nodefs-provider-sample', excludeFromReadme: true, path: 'nodefs-provider-sample', guide: null, apis: [], contributions: [] },

jupyter-server-provider-sample/.eslintrc.js

@@ -0,0 +1,23 @@
+/**@type {import('eslint').Linter.Config} */
+// eslint-disable-next-line no-undef
+module.exports = {
+	root: true,
+	parser: '@typescript-eslint/parser',
+	plugins: [
+		'@typescript-eslint',
+	],
+	extends: [
+		'eslint:recommended',
+		'plugin:@typescript-eslint/recommended',
+	],
+	rules: {
+		'semi': [
+			2,
+			"always"
+		],
+		'@typescript-eslint/no-unused-vars': 0,
+		'@typescript-eslint/no-explicit-any': 0,
+		'@typescript-eslint/explicit-module-boundary-types': 0,
+		'@typescript-eslint/no-non-null-assertion': 0,
+	}
+};

jupyter-server-provider-sample/.vscode/extensions.json

@@ -0,0 +1,6 @@
+{
+  "recommendations": [
+    "dbaeumer.vscode-eslint",
+	"ms-toolsai.jupyter"
+  ]
+}

jupyter-server-provider-sample/.vscode/launch.json

@@ -0,0 +1,22 @@
+// A launch configuration that compiles the extension and then opens it inside a new window
+// Use IntelliSense to learn about possible attributes.
+// Hover to view descriptions of existing attributes.
+// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Run Extension",
+      "type": "extensionHost",
+      "request": "launch",
+      "args": [
+        "--extensionDevelopmentPath=${workspaceFolder}"
+      ],
+      "outFiles": [
+        "${workspaceFolder}/out/**/*.js"
+      ],
+      "trace": true,
+      "preLaunchTask": "npm: compile"
+    }
+  ]
+}

jupyter-server-provider-sample/.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+  "search.exclude": {
+    "out": true
+  },
+  "typescript.tsc.autoDetect": "off"
+}

jupyter-server-provider-sample/.vscode/tasks.json

@@ -0,0 +1,13 @@
+// See https://go.microsoft.com/fwlink/?LinkId=733558
+// for the documentation about the tasks.json format
+{
+	"version": "2.0.0",
+	"tasks": [
+		{
+			"type": "npm",
+			"script": "compile",
+			"problemMatcher": ["$tsc"],
+			"group": "build"
+		}
+	]
+}

jupyter-server-provider-sample/.vscodeignore

@@ -0,0 +1,12 @@
+.vscode/**
+.vscode-test/**
+out/test/**
+src/**
+.gitignore
+.yarnrc
+vsc-extension-quickstart.md
+**/tsconfig.json
+**/.eslintrc.json
+**/*.map
+**/*.ts
+**/*.tsbuildinfo

jupyter-server-provider-sample/README.md

@@ -0,0 +1,29 @@
+# Jupyter Server Provider Sample
+
+This is a very simple extension sample demonstrating the use of the Jupyter Extension API allowing other extensions to contribute [Jupyter](https://jupyter.org/) Servers via the Kernel Picker for Jupyter notebooks:
+
+- The sample extension finds Jupyter Servers running locally on the current machine
+- This list of servers is then provided to the Jupyter extension via the Jupyter Extension API
+- Upon opening a notebook and selecting a kernel the option `Local JupyterLab Servers...` will display the above servers.
+- From there, the user can select a kernel and run code in the notebook against one of the local kernels.
+- Sample showcases the use of the `back` button to allow the user to go back to the previous step.
+- Sample showcases the use of custom quick picks to get additional information from the user.
+
+## Running this sample
+
+ 1. `cd jupyter-server-provider-sample`
+ 1. `code .`: Open the folder in VS Code
+ 1. Run `npm install` in terminal to install dependencies
+ 1. Run the `Run Extension` target in the Debug View. This will:
+	- Start a task `npm: watch` to compile the code
+	- Run the extension in a new VS Code window
+ 1. Select the kernel Picker for a notebook and select the option `Local JupyterLab Servers...`
+ 1. To see servers show up in this list, start JupyterLab or Jupyter Notebook outside VS Code or from within the integrated terminal (e.g. [jupyter lab](https://jupyterlab.readthedocs.io/en/stable/getting_started/starting.html))
+
+### Guidelines
+
+1. When displaying a custom UI in the kernel picker, please ensure to add a `back` button to allow the user to go back to the previous step.
+The sample shows the use of the `back` button and how throwing `CancellationError` vs returning `undefined` helps Jupyter extension distinguish between `cancel` vs `back` behaviour.
+2. Minimize creating multiple collections, as this will result in multiple steps to selecting a kernel.
+
+![Demo](demo.gif)