Docs: Trey edits to vscode guide (#4428)

Author: treysp

docs/installation.md

@@ -24,21 +24,24 @@ pip install sqlmesh
 ```
 
 ## Install extras
-Some SQLMesh functionality requires additional Python libraries.
+Some SQLMesh functionality requires additional Python libraries, which are bundled with SQLMesh via "extras".
 
-`pip` will automatically install them for you if you specify the relevant name in brackets. For example, you install the SQLMesh browser UI extras with `pip install "sqlmesh[web]"`.
+In your `pip` command, specify the extra's name in brackets to automatically install the additional libraries. For example, you install the SQLMesh Github CI/CD bot extras with `pip install "sqlmesh[github]"`.
 
-Some extras add features, like the SQLMesh browser UI or Github CI/CD bot:
+There are two types of extras.
+
+Some extras add features, like the SQLMesh VSCode extension or Github CI/CD bot:
 
 ??? info "Feature extras commands"
     | Feature             | `pip` command                   |
     | ------------------- | ------------------------------- |
-    | Browser UI          | `pip install "sqlmesh[web]"`    |
+    | VSCode extension    | `pip install "sqlmesh[lsp]"`    |
+    | Github CI/CD bot    | `pip install "sqlmesh[github]"` |
     | dbt projects        | `pip install "sqlmesh[dbt]"`    |
     | dlt projects        | `pip install "sqlmesh[dlt]"`    |
-    | Github CI/CD bot    | `pip install "sqlmesh[github]"` |
     | Slack notifications | `pip install "sqlmesh[slack]"`  |
     | Development setup   | `pip install "sqlmesh[dev]"`    |
+    | Browser UI          | `pip install "sqlmesh[web]"`    |
     | LLM SQL prompt      | `pip install "sqlmesh[llm]"`    |
 
 Other extras are required to use specific SQL engines, like Bigquery or Postgres:
@@ -47,6 +50,7 @@ Other extras are required to use specific SQL engines, like Bigquery or Postgres
     | SQL engine    | `pip` command                        |
     | ------------- | ------------------------------------ |
     | Athena        | `pip install "sqlmesh[athena]"`      |
+    | Azure SQL     | `pip install "sqlmesh[azuresql]"`    |
     | Bigquery      | `pip install "sqlmesh[bigquery]"`    |
     | ClickHouse    | `pip install "sqlmesh[clickhouse]"`  |
     | Databricks    | `pip install "sqlmesh[databricks]"`  |
@@ -55,10 +59,11 @@ Other extras are required to use specific SQL engines, like Bigquery or Postgres
     | MySQL         | `pip install "sqlmesh[mysql]"`       |
     | Postgres      | `pip install "sqlmesh[postgres]"`    |
     | Redshift      | `pip install "sqlmesh[redshift]"`    |
+    | RisingWave    | `pip install "sqlmesh[risingwave]"`  |
     | Snowflake     | `pip install "sqlmesh[snowflake]"`   |
     | Trino         | `pip install "sqlmesh[trino]"`       |
 
-Multiple extras can be installed at once, as in `pip install "sqlmesh[web,slack]"`.
+Multiple extras can be installed at once, as in `pip install "sqlmesh[github,slack]"`.
 
 ## Next steps
 

docs/quickstart/vscode.md

@@ -2,112 +2,153 @@
 
 !!! danger "Preview"
 
-    The extension is currently in preview and as such is subject to change. You may encounter bugs and API incompatibilities with the SQLMesh version you are running. We encourage you to try it and raise any issues [here](https://github.com/tobikodata/sqlmesh/issues).
+    The SQLMesh Visual Studio Code extension is in preview and undergoing active development. You may encounter bugs or API incompatibilities with the SQLMesh version you are running.
 
-In this quickstart guide, you'll set up the SQLMesh extension in Visual Studio Code. We'll show you the capabilities of the extension and how to troubleshoot common issues.
+    We encourage you to try the extension and [create Github issues](https://github.com/tobikodata/sqlmesh/issues) for any problems you encounter.
+
+In this guide, you'll set up the SQLMesh extension in the Visual Studio Code IDE software (which we refer to as "VSCode").
+
+We'll show you the capabilities of the extension and how to troubleshoot common issues.
 
 ## Installation
 
-Installation is done through the official [marketplace](https://marketplace.visualstudio.com/items?itemName=tobikodata.sqlmesh) or by searching for `SQLMesh` in the "Extensions" tab of Visual Studio Code. 
+### VSCode extension
+
+Install the extension through the official Visual Studio [marketplace website](https://marketplace.visualstudio.com/items?itemName=tobikodata.sqlmesh) or by searching for `SQLMesh` in the VSCode "Extensions" tab.
 
-For further guidance on how to install extensions, see the [relevant Visual Studio Code documentation](https://code.visualstudio.com/docs/configure/extensions/extension-marketplace#_install-an-extension).  
+Learn more about installing VSCode extensions in the [official documentation](https://code.visualstudio.com/docs/configure/extensions/extension-marketplace#_install-an-extension).
 
-### Recommended setup
+### Python setup
 
-While installing the extension is simple, setting up a Python environment correctly is a bit more involved. We do recommend using a dedicated *Python virtual environment* to install SQLMesh. For a complete guide, visit the [Python documentation](https://docs.python.org/3/library/venv.html), but the following steps will create the virtual environment, activate it, and install SQLMesh for both a SQLMesh core setup and a Tobiko Cloud setup.
+While installing the extension is simple, setting up and configuring a Python environment in VSCode is a bit more involved.
 
-#### SQLMesh Core
+We recommend using a dedicated *Python virtual environment* to install SQLMesh. Visit the [Python documentation](https://docs.python.org/3/library/venv.html) for more information about virtual environments.
 
-For SQLMesh core, you can create a virtual environment, activate it and install SQLMesh as follows:
+We describe the steps to create and activate a virtual environment below, but additional information is available on the [SQLMesh installation page](installation.md).
+
+We first install the SQLMesh library, which is required by the extension.
+
+Open a terminal instance in your SQLMesh project's directory and issue this command to create a virtual environment in the `.venv` directory:
 
 ```bash
 python -m venv .venv
-source .venv/bin/activate
-pip install 'sqlmesh[lsp]'
 ```
 
-Once you have the virtual environment, you can ensure that Visual Studio Code is using the correct Python interpreter by going to the [command palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette) and running `Python: Select Interpreter`. Select the Python executable in the virtual environment.
+Next, activate the virtual environment:
 
-![Select interpreter](./vscode/select_interpreter.png)
+```bash
+source .venv/bin/activate
+```
 
-Once that's done, you can validate that the extension is correctly using the virtual environment by checking the `sqlmesh` output channel in the [output panel](https://code.visualstudio.com/docs/getstarted/userinterface#_output-panel), which details the Python path and the details of your SQLMesh installation and looks as follows:
+#### Open-source SQLMesh
 
-![Output panel](./vscode/interpreter_details.png)
+If you are using open-source SQLMesh, install SQLMesh with the `lsp` extra that enables the VSCode extension (learn more about SQLMesh extras [here](installation.md#install-extras)):
+
+```bash
+pip install 'sqlmesh[lsp]'
+```
 
 #### Tobiko Cloud
 
-For Tobiko Cloud, the `tcloud` utility is used to install SQLMesh, so you'll need to set up a Python environment, activate it, and install SQLMesh using the tcloud utility as follows.
+If you are using Tobiko Cloud, the `tcloud` library will install SQLMesh for you.
+
+First, follow the [Python setup](#python-setup) steps above to create and activate a Python environment. Next, install `tcloud`:
 
 ```bash
-python -m venv .venv
-source .venv/bin/activate
 pip install tcloud
 ```
 
-Once you have the virtual environment, you can ensure that Visual Studio Code is using the correct Python interpreter by going to the [command palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette) and running `Python: Select Interpreter`. Select the Python executable in the virtual environment.
+Finally, add the `lsp` extra to your `tcloud.yml` configuration file, as described [here](../cloud/tcloud_getting_started.md#connect-tobiko-cloud-to-data-warehouse).
+
+### VSCode Python interpreter
+
+A Python virtual environment contains its own copy of Python (the "Python interpreter"). We need to make sure VSCode is using your virtual environment's interpreter rather than a system-wide or other interpreter that does not have access to the SQLMesh library we just installed.
+
+Confirm that VSCode is using the correct interpreter by going to the [command palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette) and clicking `Python: Select Interpreter`. Select the Python executable that's in the virtual environment's directory `.venv`.
 
 ![Select interpreter](./vscode/select_interpreter.png)
 
-You can use the `tcloud` commands in your terminal to perform operations as usual, or the extension exposes the same commands through the command palette under the following commands:
-- `Sign in to Tobiko Cloud`
-- `Sign out of Tobiko Cloud`
+Once that's done, validate that the everything is working correctly by checking the `sqlmesh` channel in the [output panel](https://code.visualstudio.com/docs/getstarted/userinterface#_output-panel). It displays the Python interpreter path and details of your SQLMesh installation:
 
-## Features
+![Output panel](./vscode/interpreter_details.png)
 
-### Lineage 
+## Features
 
-The extension adds a lineage view to SQLMesh models. To view the lineage of a model, use the `Lineage` tab in the panel as shown below:
+SQLMesh's VSCode extension makes it easy to edit and understand your SQLMesh project with these features:
 
-![Lineage view](./vscode/lineage.png)
+- Lineage
+    - Interactive view of model lineage
+- Editor
+    - Auto-completion for model names and SQLMesh keywords
+    - Model summaries when hovering over model references
+    - Links to open model files from model references
+    - Inline SQLMesh linter diagnostics
+- VSCode commands
+    - Format SQLMesh project files
+    - Sign in/out of Tobiko Cloud (Tobiko Cloud users only)
 
-### Commands
+### Lineage
 
-The extension exposes the following commands through the command palette:
+The extension adds a lineage view to SQLMesh models. To view the lineage of a model, go to the `Lineage` tab in the panel:
 
-- `Sign in to Tobiko Cloud`
-- `Sign out of Tobiko Cloud`
-- `Format SQLMesh project`
+![Lineage view](./vscode/lineage.png)
 
-### LSP Features 
+### Editor
 
-The SQLMesh LSP adds several features to the editor:
+The SQLMesh VSCode extension includes several features that make editing SQLMesh models easier and quicker:
 
 **Completion**
 
-When writing SQL models, keywords, or model names, you should see completion suggestions.
+See auto-completion suggestions when writing SQL models, keywords, or model names.
 
 ![Completion](./vscode/autocomplete.png)
 
 **Go to definition and hover information**
 
-The SQLMesh LSP adds a definition provider for SQLMesh models. When you hover over a model name, you should see a tooltip with the model description, and when you click, you will be taken to the model definition.
+Hovering over a model name shows a tooltip with the model description. Clicking the model name opens the file containing the model definition.
 
 **Diagnostics**
 
-The SQLMesh LSP adds a diagnostic provider for your SQLMesh project. If you have the SQLMesh linter enabled, issues will be reported in your editor. This works for both SQLMesh built-in rules and custom rules.
+If you have the [SQLMesh linter](../guides/linter.md) enabled, issues are reported directly in your editor. This works for both SQLMesh's built-in linter rules and custom linter rules.
 
 ![Diagnostics](./vscode/diagnostics.png)
 
 **Formatting**
 
-The SQLMesh LSP also adds a formatting provider for SQLMesh models. When you write SQL models, you can use the formatter to format models consistently.
+SQLMesh's model formatting tool is integrated directly into the editor, so it's easy to format models consistently.
+
+### Commands
+
+The SQLMesh VSCode extension provides the following commands in the VSCode command palette:
+
+- `Format SQLMesh project`
+- `Sign in to Tobiko Cloud` (Tobiko Cloud users only)
+- `Sign out of Tobiko Cloud` (Tobiko Cloud users only)
 
 ## Troubleshooting
 
-### LSP extensions
+### Python environment woes
+
+The most common problem is the extension not using the correct Python interpreter.
+
+Follow the [setup process described above](#vscode-python-interpreter) to ensure that the extension is using the correct Python interpreter.
+
+If you have checked the VSCode `sqlmesh` output channel and the extension is still not using the correct Python interpreter, please raise an issue [here](https://github.com/tobikodata/sqlmesh/issues).
+
+### Missing Python dependencies
 
-When installing SQLMesh, some dependencies that are required by the extension are not installed by default. You can install them by running the following command in your terminal. Specifying the `[lsp]` flag will install the dependencies required by the extension.
+When installing SQLMesh, some dependencies required by the VSCode extension are not installed unless you specify the `lsp` "extra".
+
+If you are using open-source SQLMesh, install the `lsp` extra by running this command in your terminal:
 
 ```bash
 pip install 'sqlmesh[lsp]'
 ```
 
-If you are in a cloud environment, you can ensure the extension requirements are correctly installed by adding `lsp` to the list of extras required in the `tcloud.yaml` file.
-
-### Python environment woes
-
-The most common issue is that the extension is not using the correct Python interpreter. We recommend following the [recommended setup](#recommended-setup) to ensure that the extension is using the correct Python interpreter. If you have checked the `sqlmesh` output channel and the extension is still not using the correct Python interpreter, please raise an issue [here](https://github.com/tobikodata/sqlmesh/issues).
+If you are using Tobiko Cloud, make sure `lsp` is included in the list of extras specified in the [`tcloud.yaml` configuration file](../cloud/tcloud_getting_started.md#connect-tobiko-cloud-to-data-warehouse).
 
 ### SQLMesh compatibility
 
-While the extension is in preview and the APIs to the underlying SQLMesh version are not stable, we do not guarantee compatibility between the extension and the SQLMesh version you are using. If you encounter an issue, please raise an issue [here](https://github.com/tobikodata/sqlmesh/issues).
+While the SQLMesh VSCode extension is in preview and the APIs to the underlying SQLMesh version are not stable, we do not guarantee compatibility between the extension and the SQLMesh version you are using.
+
+If you encounter a problem, please raise an issue [here](https://github.com/tobikodata/sqlmesh/issues).

docs/quickstart/vscode/interpreter_details.png

@@ -30,9 +30,10 @@ nav:
       - guides/testing.md
       - guides/model_selection.md
     - SQLMesh tools:
-      - guides/ui.md
+      - quickstart/vscode.md
       - guides/tablediff.md
       - guides/linter.md
+      - guides/ui.md
       - guides/observer.md
     - Advanced usage:
       - guides/customizing_sqlmesh.md