docs: refresh documentation for running without a devcontainer (#956)

Co-authored-by: Arpit Gaur <gaurarpit@gmail.com>

.devcontainer/devcontainer.json

@@ -12,7 +12,7 @@
 		"ghcr.io/rchaganti/vsc-devcontainer-features/azurebicep:1.0.5": {}
 	},
 
-	"postCreateCommand": "./.devcontainer/postCreate.sh",
+	"postCreateCommand": "./.devcontainer/setupEnv.sh",
 
 	"customizations": {
 		"vscode": {

.vscode/extensions.json

@@ -1,6 +1,18 @@
 {
   "recommendations": [
+    "github.vscode-pull-request-github",
+    "github.vscode-github-actions",
+    "ms-azuretools.azure-dev",
     "ms-azuretools.vscode-azurefunctions",
-    "ms-python.python"
+    "ms-azuretools.vscode-bicep",
+    "ms-azuretools.vscode-docker",
+    "ms-python.python",
+    "ms-python.black-formatter",
+    "ms-python.vscode-pylance",
+    "ms-python.pylint",
+    "ms-toolsai.jupyter",
+    "ms-vscode.vscode-node-azure-pack",
+    "TeamsDevApp.ms-teams-vscode-extension",
+    "zeshuaro.vscode-python-poetry"
   ]
-}
+}

CONTRIBUTING.md

@@ -38,7 +38,7 @@ Poetry is a package manager for Python that allows developers to manage dependen
 
 Poetry is setup for you in the devcontainer, but should you need to set this up manually you can
 ```sh
-sh ./.devcontainer/postCreate.sh
+sh ./.devcontainer/setupEnv.sh
 ```
 
 The following manual steps can also be followed to setup poetry:

docs/LOCAL_DEPLOYMENT.md

@@ -2,6 +2,8 @@
 
 # Local setup
 
+> **Note for macOS Developers**: If you are using macOS on Apple Silicon (ARM64) the DevContainer will **not** work. This is due to a limitation with the Azure Functions Core Tools (see [here](https://github.com/Azure/azure-functions-core-tools/issues/3112)). We recommend using the [Non DevContainer Setup](./NON_DEVCONTAINER_SETUP.md) instructions to run the accelerator locally.
+
 The easiest way to run this accelerator is in a VS Code Dev Containers, which will open the project in your local VS Code using the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers):
 
 1. Start Docker Desktop (install it if not already installed)

docs/NON_DEVCONTAINER_SETUP.md

@@ -1,54 +1,55 @@
 [Back to *Chat with your data* README](../README.md)
 
-# Project setup
+# Non-DevContainer Setup
 
-If you are unable to run this accelerator as a DevContainer or in CodeSpaces, then you will need.
+If you are unable to run this accelerator using a DevContainer or in GitHub CodeSpaces, then you will need to install the following prerequisites on your local machine.
 
-- [Visual Studio Code](https://code.visualstudio.com/)
-    - Extensions
-        - [Azure Functions](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurefunctions)
-        - [Azure Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-node-azure-pack)
-        - [Bicep](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-bicep)
-        - [Pylance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance)
-        - [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
-        - [Teams Toolkit](https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension) (optional: Teams extension only)
-- Install [Node.js](https://nodejs.org/en)
-  - Install the LTS version (Recommended for Most Users)
+- A code editor. We recommend [Visual Studio Code](https://code.visualstudio.com/), with the following extensions:
+  - [Azure Functions](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurefunctions)
+  - [Azure Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-node-azure-pack)
+  - [Bicep](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-bicep)
+  - [Pylance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance)
+  - [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
+  - [Teams Toolkit](https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension) **Optional**
+- [Python 3.11](https://www.python.org/downloads/release/python-3119/)
+- [Node.js LTS](https://nodejs.org/en)
+- [Azure Developer CLI](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd)
+- [Azure Functions Core Tools](https://docs.microsoft.com/en-us/azure/azure-functions/functions-run-local)
 
+## Setup
 
-### Running the sample using the Azure Developer CLI (azd)
+1. Review the contents of [.devcontainer/setupEnv.sh](../.devcontainer/setupEnv.sh) and then run it:
 
-The Azure Developer CLI (`azd`) is a developer-centric command-line interface (CLI) tool for creating Azure applications.
+    ```bash
+    .devcontainer/setupEnv.sh
+    ```
 
-You need to install it before running and deploying with the Azure Developer CLI. (If you use the devcontainer, everything is already installed)
+1. Select the Python interpreter in Visual Studio Code:
 
-### Windows
+    - Open the command palette (`Ctrl+Shift+P` or `Cmd+Shift+P`).
+    - Type `Python: Select Interpreter`.
+    - Select the Python 3.11 environment created by Poetry.
 
-```powershell
-powershell -ex AllSigned -c "Invoke-RestMethod 'https://aka.ms/install-azd.ps1' | Invoke-Expression"
-```
+### Running the sample using the Azure Developer CLI (azd)
+
+The Azure Developer CLI (`azd`) is a developer-centric command-line interface (CLI) tool for creating Azure applications.
 
-### Linux/MacOS
+1. Log in to Azure using `azd`:
 
-```
-curl -fsSL https://aka.ms/install-azd.sh | bash
-```
+    ```
+    azd auth login
+    ```
 
-After logging in with the following command, you will be able to use the `azd` cli to quickly provision and deploy the application.
+1. Execute the `azd init` command to initialize the environment and enter the solution accelerator name when prompted:
 
-```
-azd auth login
-```
+    ```
+    azd init -t chat-with-your-data-solution-accelerator
+    ```
 
-Then, execute the `azd init` command to initialize the environment (You do not need to run this command if you already have the code or have opened this in a Codespace or DevContainer).
-```
-azd init -t chat-with-your-data-solution-accelerator
-```
-Enter an environment name.
+1. Run `azd up` to provision all the resources to Azure and deploy the code to those resources.
 
-Then, run `azd up` to provision all the resources to Azure and deploy the code to those resources.
-```
-azd up 
-```
+    ```
+    azd up
+    ```
 
-Select your desired `subscription` and `location`. Wait a moment for the resource deployment to complete, click the website endpoint and you will see the web app page.
+    > Select your desired `subscription` and `location`. Wait a moment for the resource deployment to complete, click the website endpoint and you will see the web app page.