Merge pull request #434 from microsoft/dayland/doc-updates-for-1.0-re…

…adiness

Updates to docs based on community feedback

docs/container_webapp_debug.md

@@ -1,8 +1,8 @@
-# Debugging the Container Based Web App Locally in VSCode
+# Debugging the Enrichment Web App Locally in VSCode
 
-Embeddings processing is performed in a docker container which is deployed from the Azure Container Registry (ACR) to the Webapp. The system then uses this fucntionality to create embeddings when messages arrive in the embeddings queue. At some point you may wish to step through this code line by line in VS Code. Prior to debugging, ensure you stop the webapp in the Azure portal, or it will pick up and test messages you deliver to the embeddings queue before your code can read the message.
+Embeddings processing is performed in an Azure App Service. The system uses this functionality to perform enrichments, create embeddings, and index documents when messages arrive in the **embeddings-queue** queue. At some point you may wish to step through this code line by line in VS Code. Prior to debugging, ensure you stop the webapp in the Azure portal, or it will pick up and test messages you deliver to the embeddings queue before your code can read the message.
 
-To start debugging firstly add breakpoints to the code and then simply select the Run & Debug menu option in the left bar, or Ctrl+Shift+D. Next select Python: FastAPI - enrichment app and hit the play button. This will then initiate the code and stop on your first breakpoint.
+To start debugging firstly add breakpoints to the code and then simply select the Run & Debug menu option in the left bar, or Ctrl+Shift+D. Next select `Python: Enrichment Webapp`  and hit the play button. This will then initiate the code and stop on your first breakpoint.
 
 One tip is to save a copy of a message in the embeddings queue which triggers your logic. Then you will be able to just resubmit this message again and again to initiate and trace your code.
 

docs/deployment/deployment.md

@@ -6,9 +6,16 @@ Follow these steps to get the accelerator up and running in a subscription of yo
 
 ## Development Environment Configuration
 
-The deployment process for the IA Accelerator, uses a concept of **Developing inside a Container** to containerize all the necessary pre-requisite component without requiring them to be installed on the local machine. The environment you will work in will be created using a development container, or dev container hosted on a virtual machine using GitHub Codespaces.
+The deployment process for the IA Accelerator, uses a concept of **Developing inside a Container** to containerize all the necessary pre-requisite component without requiring them to be installed on the local machine. The environment you will work in will be created using a development container or dev container hosted on a virtual machine using GitHub Codespaces.
 
-[![Open in GitHub Codespaces](https://img.shields.io/static/v1?style=for-the-badge&label=GitHub+Codespaces&message=Open&color=brightgreen&logo=github)](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=601652366&machine=basicLinux32gb&devcontainer_path=.devcontainer%2Fdevcontainer.json&location=eastus)
+Begin by first forking the Information Assistant repository into your own repository. This can be useful for managing any changes you may require for your local environment. It will also enable you to accept and merge changes from the Information Assistant repo as future releases and hotfixes are made available.
+
+To fork the repo simply click the **Fork** button at the top of the Information Assistant Repo page and follow the steps to set up your new fork.
+![Fork the Information Assistant Repo](/docs/images/fork_repo.png)
+
+Once you have forked the repo, you can then use the following button to open the Information Assistant Codespace. You will need to select your forked repo and the location for your Codespace to run in.
+
+[![Open in GitHub Codespaces](https://img.shields.io/static/v1?style=for-the-badge&label=GitHub+Codespaces&message=Open&color=brightgreen&logo=github)](https://github.com/codespaces/new?hide_repo_select=false&ref=main&machine=basicLinux32gb&devcontainer_path=.devcontainer%2Fdevcontainer.json)
 
 Begin by setting up your own Codespace using our  [Developing in Codespaces](/docs/deployment/developing_in_a_codespaces.md) documentation.
 

docs/deployment/developing_in_a_codespaces.md

@@ -15,16 +15,17 @@ A codespace is a development environment that's hosted in the cloud. You can cus
 ---
 ## Creating your codespace
 
-1.	Click on    [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/microsoft/PubSec-Info-Assistant)
-2.	New window will open where you can create a new codespace
-3.	By default, you will be on **main** branch, you can switch to specific branch where you would like to create a codespace.
-    Also it would provide option to select **Region**,**Machine type**
-4. Then click on  **Create codespace**
-![Codespaces creation](/docs/images/codespaces_creation.png)
-
-5.	Then it automatically start building container in the github codespaces ( wait for until container successfully created)
+1. Click on    [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/)
+1. New window will open where you can create a new Codespace
+1. First you will need to select your repository you forked from the Information Assistant repo
+1. Next, by default you will be on **main** branch, you can switch to specific branch where you would like to create a Codespace.
+1. Then select options for **Region** and **Machine type**. The "Dev Container configuration" will be prepopulated and does not need to be changed.
+1. Next, click on  **Create codespace**
+![Codespaces creation](/docs/images/codespace_creation.png)
+
+1. Then it automatically start building container in the github codespaces ( wait for until container successfully created)
 ![Building container](/docs/images/codespaces_building_container.png)
-6. When you create a new codespace from a template, it is always opened in the Visual Studio Code web client. You can reopen an existing codespace in any supported editor
+1. When you create a new Codespace from a template, it is always opened in the Visual Studio Code web client. You can reopen an existing Codespace in any supported editor
 ![Codespaces in vscode](/docs/images/codespaces_open_in_vs_code_desktop.png)
 
 ---

docs/deployment/setting_up_sandbox_environment.md

@@ -50,7 +50,7 @@ To set up an Azure DevOps CI/CD pipeline for deploying code from a GitHub reposi
     TENANT_ID | The ID of the tenant that should be deployed to.
     AZURE_STORAGE_ACCOUNT<br/>AZURE_STORAGE_ACCOUNT_KEY | Bicep is used to create Infrastructure as Code. This is the storage account that the Bicep State is stored.
 	CONTAINER_REGISTRY_ADDRESS | Azure Container Registry where the Info Assistant development container will be cached during pipeline runs
-    AZURE_OPENAI_SERVICE_NAME<br/>AZURE_OPENAI_SERVICE_KEY<br/>AZURE_OPENAI_CHATGPT_DEPLOYMENT | It is recommended to point the pipeline to an existing installation of Azure OpenAI. These values will be used to target that instance.
+    AZURE_OPENAI_SERVICE_NAME<br/>AZURE_OPENAI_SERVICE_KEY<br/>AZURE_OPENAI_CHATGPT_DEPLOYMENT<br/>AZURE_OPENAI_GPT_DEPLOYMENT | It is recommended to point the pipeline to an existing installation of Azure OpenAI. These values will be used to target that instance.
     environment | The environment name that matches an environment variable file located in `./scripts/environments`. For example if the pipeline parameter is set to "demo" there needs to be a corresponding file at `/scripts/environment/demo.env`
 
 2. **Save your pipeline:** After updating the variable, save your pipeline configuration.

docs/features/optional_features.md

@@ -2,13 +2,13 @@
 
 Please see below sections for coverage of IA Accelerator optional features.
 
-* [Configuring your own language ENV file](/docs/features/features.md#configuring-your-own-language-env-file)
-* [Debugging functions](/docs/features/features.md#debugging-functions)
-* [Debugging the web app](/docs/features/features.md#debugging-the-web-app)
-* [Debugging the container web app](/docs/features/features.md#debugging-the-container-web-app)
-* [Build pipeline for Sandbox](/docs/features/features.md#build-pipeline-for-sandbox)
-* [Customer Usage Attribution](/docs/features/features.md#customer-usage-attribution)
-* [Sovereign Region Deployment](/docs/features/features.md#sovereign-region-deployment)
+* [Configuring your own language ENV file](#configuring-your-own-language-env-file)
+* [Debugging functions](#debugging-functions)
+* [Debugging the web app](#debugging-the-web-app)
+* [Debugging the enrichment web app](#debugging-the-enrichment-web-app)
+* [Build pipeline for Sandbox](#build-pipeline-for-sandbox)
+* [Customer Usage Attribution](#customer-usage-attribution)
+* [Sovereign Region Deployment](#sovereign-region-deployment)
 * [Configure REST API access](#configure-rest-api-access)
 * [Customize Autoscale and App Service SKU's](#customize-autoscale)
 
@@ -24,9 +24,9 @@ Check out how to [Debug the Azure functions locally in VSCode](/docs/function_de
 
 Check out how to [Debug the Information Assistant Web App](/docs/webapp_debug.md)
 
-## Debugging the container web app
+## Debugging the enrichment web app
 
-Check out how to [Debug the Information Assistant Web App](/docs/container_webapp_debug.md)
+Check out how to [Debug the Information Assistant Enrichment Web App](/docs/container_webapp_debug.md)
 
 ## Build pipeline for Sandbox
 

docs/knownissues.md

@@ -17,9 +17,11 @@ Error: This subscription cannot create CognitiveServices until you agree to Resp
 4. Review and accept the terms "Responsible AI Notice".
 5. Create the Azure AI Service.
 
+***IMPORTANT:*** In some instances, an older subscription that has already had the "Responsible AI Notice" accepted for the old "Cognitive Services multi-service account" may require this process to be repeated for the new "Azure AI Service".
+
 ---
 
-## Error "Your adminstrator has configured the application infoasst_web_access_xxxxx to block users..."
+## Error "Your administrator has configured the application infoasst_web_access_xxxxx to block users..."
 
 By default Info Assistant deploys the webapp to require users to be a member of an Azure Active Directory Enterprise Application to access the website. If a user is not a member of the AAD EA they will receive this error:
 
@@ -108,3 +110,21 @@ If you see a jq parse error while doing deployments, it means one of the makefil
 
 ### Solution:
 To resolve carefully check your deployment .env file for any missing but required values. There are rare times when ARM has issues and output values are not written. In which case simply double check your configuration and rerun the ```make deploy``` and/or ```make extract-env``` command so that the bicep outputs can be written again
+
+## Error: 
+
+If you encounter an error similar to the one below that indicates your device must be managed.
+
+```
+ERROR: AADSTS530003: Your device is required to be managed to access this resource.
+Trace ID: xxxxxxxx-xxxx-xxxx-xxxxxxxx
+Correlation ID: xxxxxxxx-xxxx-xxxx-xxxxxxxx
+Timestamp: 2023-10-05 19:54:05Z
+Interactive authentication is needed. Please run:
+az login --scope https://graph.microsoft.com//.default
+make: *** [Makefile:18: infrastructure] Error 1
+```
+
+### Solution
+
+You will need to open your Codespace in VSCode on your managed device. Please read more about opening your [CodeSpace using VSCode](/docs/deployment/developing_in_a_codespaces.md#using-github-codespaces-in-visual-studio-code).

docs/webapp_debug.md

@@ -4,7 +4,7 @@ If you wish to debug the user interface, or web app that as part of this acceler
 
 The app consists of two layers, namely the frontend user interface components and the backend logic components. As a user interacts with the user interface, they are engaging with the frontend code, and control is passed to the back end code as needed, for example to make calls to the Azure OpenAI service.
 
-To debug the webapp, both frontend and backend, first set breakpoints in your code under the frontend and/or backend. Select the 'Run & Debug' tab from the sidebar in VS Code. Select Python: Flask from the dropdown and hit run. This will initiate local debugging of the backend code.
+To debug the webapp, both frontend and backend, first set breakpoints in your code under the frontend and/or backend. Select the 'Run & Debug' tab from the sidebar in VS Code. Select `Python: WebApp backend` from the dropdown and hit run. This will initiate local debugging of the backend code.
 
 ![backend debugging](/docs/images/webapp_debug_1.png)