Add getting started documentation (#82)

fjakobs · kartikgupta-db · web-flow · commit 5b91982d6426 · 2022-09-13T11:23:11.000Z
Co-authored-by: Kartik Gupta &lt;88345179+kartikgupta-db@users.noreply.github.com&gt;
diff --git a/package.json b/package.json
@@ -29,11 +29,11 @@
     "homepage": "https://github.com/databricks/databricks-vscode#readme",
     "packageManager": "yarn@3.2.1",
     "devDependencies": {
-        "@typescript-eslint/eslint-plugin": "^5.33.0",
-        "@typescript-eslint/parser": "^5.33.0",
-        "eslint": "^8.21.0",
+        "@typescript-eslint/eslint-plugin": "^5.37.0",
+        "@typescript-eslint/parser": "^5.37.0",
+        "eslint": "^8.23.1",
         "eslint-config-prettier": "^8.5.0",
         "ts-mockito": "^2.6.1",
-        "typescript": "^4.7.4"
+        "typescript": "^4.8.3"
     }
 }
diff --git a/packages/databricks-sdk-js/package.json b/packages/databricks-sdk-js/package.json
@@ -29,7 +29,7 @@
         "test:integ:cov": "nyc --report-dir ./coverage/integration yarn run test:integ"
     },
     "dependencies": {
-        "ini": "^3.0.0",
+        "ini": "^3.0.1",
         "node-fetch": "^3.2.10"
     },
     "devDependencies": {
@@ -39,13 +39,13 @@
         "@types/chai-spies": "^1.0.3",
         "@types/ini": "^1.3.31",
         "@types/mocha": "^9.1.1",
-        "@types/node": "^18.7.1",
+        "@types/node": "^18.7.17",
         "@types/tmp": "^0.2.3",
         "@types/uuid": "^8.3.4",
         "chai": "^4.3.6",
         "chai-as-promised": "^7.1.1",
         "chai-spies": "^1.0.0",
-        "eslint": "^8.20.0",
+        "eslint": "^8.23.1",
         "mocha": "^10.0.0",
         "nyc": "^15.1.0",
         "prettier": "^2.7.1",
@@ -54,8 +54,8 @@
         "ts-mocha": "^10.0.0",
         "ts-mockito": "^2.6.1",
         "ts-node": "^10.9.1",
-        "typescript": "^4.7.4",
-        "uuid": "^8.3.2"
+        "typescript": "^4.8.3",
+        "uuid": "^9.0.0"
     },
     "nyc": {
         "extends": "@istanbuljs/nyc-config-typescript",
diff --git a/packages/databricks-vscode/.vscodeignore b/packages/databricks-vscode/.vscodeignore
@@ -4,6 +4,7 @@ dist/**
 node_modules/**
 src/**
 .gitignore
+.prettierignore
 .yarnrc
 **/tsconfig.json
 **/.eslintrc.json
diff --git a/packages/databricks-vscode/README.quickstart.md b/packages/databricks-vscode/README.quickstart.md
@@ -0,0 +1,55 @@
+# Databricks Extension for VSCode
+
+The Databricks extension for VSCode allows you to develop for the Databricks Lakehouse platform from VSCode.
+
+# Features
+
+-   Synchronize code to a Databricks workspace
+-   Run Python files on a Databricks cluster
+-   Run notebooks and Python files as Jobs
+
+---
+
+# <a id="setup-steps"></a>Getting Started
+
+## Install extension
+
+1. Download and install dbx: `pip install dbx`
+2. Download the nightly release matching your platform from https://github.com/databricks/databricks-vscode/releases
+3. Install the downloaded extension using the "Extensions: Install from VSIX..." command (Cmd-Shift-P)
+
+## Configure Extension
+
+1. Open the Databricks panel by clicking on the Databricks icon on the left
+2. Click the "Configure Databricks" button
+3. Follow the wizard to select or configure a CLI profile
+4. Click the "plug" icon in the clusters tree item to select an interactive cluster for running code on (you might have to create a cluster in the web UI first if none is available)
+5. Click the "plug" icon in the Repo tree item to select an repo to sync code to (you might have to create a repo in the web UI first if none is available. The repo doesn't need to have a git remote configured.)
+
+![configure](./images/configure.gif)
+
+## Running Code
+
+Once you have your project configured you can sync your local code to the repo and run it on a cluster.
+
+### Running PySpark code
+
+1. Create python file
+2. Click the "Run" icon in the tab bar and select "Run File on Databricks"
+
+This will run the active python file on a cluster using the command execution API. The result is printed in the "debug" output panel.
+
+![configure](./images/run.gif)
+
+### Running PySpark and notebooks as a Workflow
+
+1. Create a python file or a python based notebook
+2. Click the "Run" icon in the tab bar and select "Run File as Workflow on Databricks"
+
+This will run the file using the Jobs API on a cluster and render the result in a WebView.
+
+### Running using custom run configurations
+
+Both ways of running code on a cluster are also available in custom run configurations. In the "Run and Debug" panel you can click "Add configuration..." and select either "Databricks: Launch" or "Databricks: Launch as Workflow". Using run configuration you can also pass in command line arguments and run your code by simply pressing `F5`.
+
+![configure](./images/custom-runner.gif)
diff --git a/packages/databricks-vscode/images/configure.gif b/packages/databricks-vscode/images/configure.gif
diff --git a/packages/databricks-vscode/images/custom-runner.gif b/packages/databricks-vscode/images/custom-runner.gif
diff --git a/packages/databricks-vscode/images/run.gif b/packages/databricks-vscode/images/run.gif
diff --git a/packages/databricks-vscode/package.json b/packages/databricks-vscode/package.json
@@ -56,6 +56,7 @@
         "onCommand:databricks.run.getProgramName",
         "onCommand:databricks.run.runEditorContentsAsWorkflow",
         "onCommand:databricks.run.runEditorContents",
+        "onCommand:databricks.quickstart.open",
         "onView:configurationView",
         "onView:clusterView",
         "onTaskType:databricks",
@@ -156,6 +157,10 @@
                 "category": "Databricks",
                 "enablement": "!inDebugMode",
                 "icon": "$(play)"
+            },
+            {
+                "command": "databricks.quickstart.open",
+                "title": "Databricks: Open Quickstart"
             }
         ],
         "viewsContainers": {
@@ -457,30 +462,30 @@
     "dependencies": {
         "@databricks/databricks-sdk": "*",
         "@vscode/debugadapter": "^1.57.0",
-        "@vscode/webview-ui-toolkit": "^1.0.0"
+        "@vscode/webview-ui-toolkit": "^1.0.1"
     },
     "devDependencies": {
         "@istanbuljs/nyc-config-typescript": "^1.0.2",
-        "@types/glob": "^7.2.0",
+        "@types/glob": "^8.0.0",
         "@types/mocha": "^9.1.1",
-        "@types/node": "^18.7.1",
+        "@types/node": "^18.7.17",
         "@types/tmp": "^0.2.3",
-        "@types/vscode": "^1.69.1",
-        "@typescript-eslint/eslint-plugin": "^5.33.0",
-        "@typescript-eslint/parser": "^5.33.0",
+        "@types/vscode": "^1.69.0",
+        "@typescript-eslint/eslint-plugin": "^5.37.0",
+        "@typescript-eslint/parser": "^5.37.0",
         "@vscode/test-electron": "^2.1.5",
-        "esbuild": "^0.15.1",
-        "eslint": "^8.21.0",
+        "esbuild": "^0.15.7",
+        "eslint": "^8.23.1",
         "glob": "^8.0.3",
         "mocha": "^10.0.0",
         "nyc": "^15.1.0",
         "prettier": "^2.7.1",
         "tmp-promise": "^3.0.3",
         "ts-mockito": "^2.6.1",
-        "typescript": "^4.7.4",
-        "vsce": "^2.10.0",
+        "typescript": "^4.8.3",
+        "vsce": "^2.11.0",
         "vscode-extension-tester": "^4.4.1",
-        "winston": "^3.8.1"
+        "winston": "^3.8.2"
     },
     "nyc": {
         "extends": "@istanbuljs/nyc-config-typescript",
diff --git a/packages/databricks-vscode/src/configuration/ConfigurationDataProvider.test.ts b/packages/databricks-vscode/src/configuration/ConfigurationDataProvider.test.ts
@@ -145,8 +145,8 @@ describe(__filename, () => {
                     color: undefined,
                     id: "repo",
                 },
-                id: "WORKSPACE",
-                label: 'Workspace - "None attached"',
+                id: "REPO",
+                label: 'Repo - "None attached"',
             },
         ]);
     });
diff --git a/packages/databricks-vscode/src/configuration/ConfigurationDataProvider.ts b/packages/databricks-vscode/src/configuration/ConfigurationDataProvider.ts
@@ -92,9 +92,9 @@ export class ConfigurationDataProvider
 
                 if (syncDestination) {
                     children.push({
-                        label: `Workspace`,
+                        label: `Repo`,
                         iconPath: new ThemeIcon("repo"),
-                        id: "WORKSPACE",
+                        id: "REPO",
                         collapsibleState: TreeItemCollapsibleState.Expanded,
                         contextValue:
                             this.sync.state === "RUNNING"
@@ -103,9 +103,9 @@ export class ConfigurationDataProvider
                     });
                 } else {
                     children.push({
-                        label: `Workspace - "None attached"`,
+                        label: `Repo - "None attached"`,
                         iconPath: new ThemeIcon("repo"),
-                        id: "WORKSPACE",
+                        id: "REPO",
                         collapsibleState: TreeItemCollapsibleState.Expanded,
                         contextValue: "syncDetached",
                     });
@@ -139,7 +139,7 @@ export class ConfigurationDataProvider
                 ];
             }
 
-            if (element.id === "WORKSPACE" && syncDestination) {
+            if (element.id === "REPO" && syncDestination) {
                 return [
                     {
                         label: `Sync state:`,
diff --git a/packages/databricks-vscode/src/extension.ts b/packages/databricks-vscode/src/extension.ts
@@ -21,6 +21,7 @@ import {SyncCommands} from "./sync/SyncCommands";
 import {CodeSynchronizer} from "./sync/CodeSynchronizer";
 import {BricksTaskProvider} from "./cli/BricksTasks";
 import {ProjectConfigFileWatcher} from "./configuration/ProjectConfigFileWatcher";
+import {QuickstartCommands} from "./quickstart/QuickstartCommands";
 
 export function activate(context: ExtensionContext) {
     let cli = new CliWrapper(context);
@@ -188,6 +189,16 @@ export function activate(context: ExtensionContext) {
     context.subscriptions.push(
         new ProjectConfigFileWatcher(connectionManager, workspace.rootPath)
     );
+
+    // Quickstart
+    const quickstartCommands = new QuickstartCommands(context);
+    context.subscriptions.push(
+        commands.registerCommand(
+            "databricks.quickstart.open",
+            quickstartCommands.openQuickstartCommand(),
+            quickstartCommands
+        )
+    );
 }
 
 // this method is called when your extension is deactivated
diff --git a/packages/databricks-vscode/src/quickstart/QuickstartCommands.ts b/packages/databricks-vscode/src/quickstart/QuickstartCommands.ts
@@ -0,0 +1,14 @@
+import {commands, ExtensionContext, Uri} from "vscode";
+
+export class QuickstartCommands {
+    constructor(private context: ExtensionContext) {}
+
+    openQuickstartCommand() {
+        return async () => {
+            const uri = Uri.file(
+                this.context.asAbsolutePath("README.quickstart.md")
+            );
+            await commands.executeCommand("markdown.showPreview", uri);
+        };
+    }
+}
diff --git a/yarn.lock b/yarn.lock
