creating the docs

Author: benfdking

docs/development.md

@@ -1,51 +1,124 @@
 # Contribute to development
-SQLMesh is licensed under [Apache 2.0](https://github.com/TobikoData/sqlmesh/blob/main/LICENSE). We encourage community contribution and would love for you to get involved.
+
+SQLMesh is licensed under [Apache 2.0](https://github.com/TobikoData/sqlmesh/blob/main/LICENSE). We encourage community contribution and would love for you to get involved. The following document outlines the process to contribute to SQLMesh.
 
 ## Prerequisites
+
+Before you begin, ensure you have the following installed on your machine. Exacltly how to install these is dependent on your operating system.
+
 * Docker
 * Docker Compose V2
 * OpenJDK >= 11
 * Python >= 3.9 < 3.13
 
-## Commands reference
+## Virtual environment setup
+
+We do recommend using a virtual environment to develop SQLMesh.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+```
+
+Once you have activated your virtual environment, you can install the dependencies by running the following command.
 
-Install dev dependencies:
 ```bash
 make install-dev
 ```
+
+Optionally, you can use pre-commit to automatically run linters/formatters:
+
+```bash
+make install-pre-commit
+```
+
+## Python development
+
 Run linters and formatters:
+
 ```bash
 make style
 ```
+
 Run faster tests for quicker local feedback:
+
 ```bash
 make fast-test
 ```
+
 Run more comprehensive tests that run on each commit:
+
 ```bash
 make slow-test
 ```
+
 Run Airflow tests that will run when PR is merged to main:
+
 ```bash
 make airflow-docker-test-with-env
 ```
-Install docs dependencies:
+
+## Documentation
+
+In order to run the documentation server, you will need to install the dependencies by running the following command.
+
 ```bash
 make install-doc
 ```
-Run docs server:
+
+Once you have installed the dependencies, you can run the documentation server by running the following command.
+
 ```bash
 make docs-serve
 ```
+
 Run docs tests:
+
 ```bash
 make doc-test
 ```
+
+## UI development
+
+In addition to the Python development, you can also develop the UI.
+
+The UI is built using React and Typescript. To run the UI, you will need to install the dependencies by running the following command.
+
+```bash
+npm install 
+```
+
 Run ide:
+
 ```bash
 make ui-up
 ```
-(Optional) Use pre-commit to automatically run linters/formatters:
-```bash
-make install-pre-commit
+
+## Developing the VSCode extension
+
+Developing the VSCode extension is most easily done by launching the debug process from a visual studio code workspace.
+
+By default, the VSCode extension will run the SQLMesh server locally and open a new visual studio code window that allows you to try out the SQLMesh IDE. It by default opens the `examples/sushi` project. 
+
+Please see the below diagram for a high level overview of the UI.
+
+```mermaid
+graph TD
+    A[VSCode Extension] --> |start server| B[SQLMesh Server]
+    A --> |creates webviews| C[Webviews]
+    C --> |reads react webpages from| B
+    A --> |calls lsp| B
+    React[React App] --> |embedded in| B
+```
+
+For development purposes, the React app is not embedded into the python server. Instead a separate instance of the React app is run. This allows you to make changes to the UI and see them immediately.
+
+This makes the architecture diagram at development time look like the following.
+
+```mermaid
+graph TD
+    A[VSCode Extension] --> |start server| B[SQLMesh Server]
+    A --> |creates webviews| C[Webviews]
+    React [React Server] --> |passes on api requests| B
+    C --> |reads react webpages from| React
 ```

vscode/assets/images/dag.svg

@@ -12,6 +12,24 @@
   "activationEvents": [],
   "main": "./dist/extension.js",
   "contributes": {
+    "viewsContainers": {
+    "panel": [
+      {
+        "id": "lineage_view",
+        "title": "Lineage",
+        "icon": "./assets/images/dag.svg"
+      }
+    ]
+    },
+   "views": {
+      "lineage_view": [
+        {
+          "id": "sqlmesh.lineage",
+          "name": "",
+          "type": "webview"
+        }
+      ]
+    },
     "commands": [
       {
         "command": "sqlmesh.format",

vscode/package.json

@@ -13,6 +13,7 @@ import { checkIfConfigurationChanged } from './common/settings'
 import { getInterpreterFromSetting } from './common/settings'
 import { startWebServer, WebServer } from './web-server/server'
 import { isErr } from './functional/result'
+import { LineagePanel } from './webviews/lineagePanel'
 
 let lsClient: LanguageClient | undefined
 let webServer: WebServer | undefined
@@ -112,6 +113,12 @@ export function activate(context: vscode.ExtensionContext) {
 
 	startServer(serverOutputChannel)
 
+	// Register the webview
+	const lineagePanel = new LineagePanel(context.extensionUri, () => webServer?.url ?? "")
+	context.subscriptions.push(
+		vscode.window.registerWebviewViewProvider(LineagePanel.viewType, lineagePanel)
+	)
+
 	setImmediate(async () => {
 		const interpreterDetails = await getInterpreterDetails()
 		if (interpreterDetails.path) {
@@ -121,7 +128,7 @@ export function activate(context: vscode.ExtensionContext) {
 	traceInfo("Extension activated")
 }
 
-export async function startServer(serverOutputChannel: vscode.LogOutputChannel) {
+export async function startServer(serverOutputChannel: vscode.LogOutputChannel): Promise<WebServer> {
     if (webServer) {
         return webServer
     }

vscode/src/extension.ts

@@ -0,0 +1,86 @@
+import {
+    CancellationToken,
+    commands,
+    Disposable,
+    TextEditor,
+    Uri,
+    WebviewView,
+    WebviewViewProvider,
+    WebviewViewResolveContext,
+    window,
+    workspace,
+  } from "vscode"
+  
+  export class LineagePanel implements WebviewViewProvider, Disposable {
+    public static readonly viewType = "sqlmesh.lineage"
+  
+    private panel: WebviewView | undefined
+    private getServerUrl: () => string
+    private _extensionUri: Uri
+  
+    public constructor(		
+        extensionUri: Uri,
+        getServerUrl: () => string
+    ) {
+      this._extensionUri = extensionUri
+      this.getServerUrl = getServerUrl
+      window.onDidChangeActiveTextEditor((event: TextEditor | undefined) => {
+        if (this.panel) {
+          this.panel.webview.html = this.getHtml()
+        }
+      })
+    }
+
+    private getPanel() {
+      return this.panel
+    }
+
+    public resolveWebviewView(
+		webviewView: WebviewView,
+		_context: WebviewViewResolveContext,
+		_token: CancellationToken,
+	) {
+        if (this.panel) {
+            webviewView = this.panel
+        }
+		this.panel = webviewView
+
+		webviewView.webview.options = {
+			// Allow scripts in the webview
+			enableScripts: true,
+			localResourceRoots: [
+				this._extensionUri
+			]
+		}
+
+    // Set content options for external URL access
+    const externalUrl = this.getServerUrl();
+    const externalAuthority = new URL(externalUrl).origin;
+    
+    webviewView.webview.html = this.getHtml()
+	}
+
+  getHtml() {
+    const externalUrl = this.getServerUrl()
+    const externalAuthority = new URL(externalUrl).origin;
+    
+    return `
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="Content-Security-Policy" content="default-src 'none'; frame-src ${externalAuthority}; script-src 'unsafe-inline'; style-src 'unsafe-inline';">
+</head>
+<body>
+  <div>${externalUrl}</div>
+  <iframe src="${externalUrl}" style="width:100%; height:100vh;" frameborder="0"></iframe>
+</body>
+</html>        `
+  }
+
+
+    dispose() {
+        // WebviewView doesn't have a dispose method
+        // We can clear references
+        this.panel = undefined;
+    }
+  }

vscode/src/webviews/lineagePanel.ts

@@ -0,0 +1,3 @@
+function AppVSCode() {
+    return <div>AppVscode</div>
+}