New documentation on App Service debugging, and some docs organizational changes (#1261)

* Docs reorg and new doc

* Index re-org

* Add link to TOC

* Update screenshots

* Fix en-us references

* Add CI

* Update section on CICD

* Fix some links

* Adding learn.com link

Author: pamelafox

README.md

@@ -0,0 +1,15 @@
+# Additional documentation
+
+Consult the main [README](../README.md) for general information about the project.
+These are advanced topics that are not necessary for a basic deployment.
+
+* [Deploying with the Azure Developer CLI](azd.md)
+* [Deploying from a free account](deploy_lowcost.md)
+* [Debugging the app on App Service](appservice.md)
+* [Local development](localdev.md)
+* [App customization](customization.md)
+* [Data ingestion](data_ingestion.md)
+* [Productionizing](productionizing.md)
+* [Login and access control](login_and_acl.md)
+* [Using GPT-4 Turbo with Vision](gpt4v.md)
+* [Alternative RAG chat samples](other_samples.md)

docs/README.md

@@ -0,0 +1,54 @@
+# Deploying with the Azure Developer CLI
+
+This guide includes advanced topics that are not necessary for a basic deployment. If you are new to the project, please consult the main [README](../README.md#deploying-from-scratch) for steps on deploying the project.
+
+[📺 Watch: Deployment of your chat app](https://www.youtube.com/watch?v=mDFZdmn7nhk)
+
+* [How does `azd up` work?](#how-does-azd-up-work)
+* [Configuring continuous deployment](#configuring-continuous-deployment)
+  * [GitHub actions](#github-actions)
+  * [Azure DevOps](#azure-devops)
+
+## How does `azd up` work?
+
+The `azd up` command comes from the [Azure Developer CLI](https://learn.microsoft.com/azure/developer/azure-developer-cli/overview), and takes care of both provisioning the Azure resources and deploying code to the selected Azure hosts.
+
+The `azd up` command uses the `azure.yaml` file combined with the infrastructure-as-code `.bicep` files in the `infra/` folder. The `azure.yaml` file for this project declares several "hooks" for the prepackage step and postprovision steps. The `up` command first runs the `prepackage` hook which installs Node dependencies and builds the React.JS-based JavaScript files. It then packages all the code (both frontend and backend) into a zip file which it will deploy later.
+
+Next, it provisions the resources based on `main.bicep` and `main.parameters.json`. At that point, since there is no default value for the OpenAI resource location, it asks you to pick a location from a short list of available regions. Then it will send requests to Azure to provision all the required resources. With everything provisioned, it runs the `postprovision` hook to process the local data and add it to an Azure AI Search index.
+
+Finally, it looks at `azure.yaml` to determine the Azure host (appservice, in this case) and uploads the zip to Azure App Service. The `azd up` command is now complete, but it may take another 5-10 minutes for the App Service app to be fully available and working, especially for the initial deploy.
+
+Related commands are `azd provision` for just provisioning (if infra files change) and `azd deploy` for just deploying updated app code.
+
+## Configuring continuous deployment
+
+This repository includes both a GitHub Actions workflow and an Azure DevOps pipeline for continuous deployment with every push to `main`. The GitHub Actions workflow is the default, but you can switch to Azure DevOps if you prefer.
+
+More details are available in [Learn.com: Configure a pipeline and push updates](https://learn.microsoft.com/azure/developer/azure-developer-cli/configure-devops-pipeline?tabs=GitHub)
+
+### GitHub actions
+
+After you have deployed the app once with `azd up`, you can enable continuous deployment with GitHub Actions.
+
+Run this command to set up a Service Principal account for CI deployment and to store your `azd` environment variables in GitHub Actions secrets:
+
+```shell
+azd pipeline config
+```
+
+You can trigger the "Deploy" workflow manually from your GitHub actions, or wait for the next push to main.
+
+If you change your `azd` environment variables at any time (via `azd env set` or as a result of provisioning), re-run that command in order to update the GitHub Actions secrets.
+
+### Azure DevOps
+
+After you have deployed the app once with `azd up`, you can enable continuous deployment with Azure DevOps.
+
+Run this command to set up a Service Principal account for CI deployment and to store your `azd` environment variables in GitHub Actions secrets:
+
+```shell
+azd pipeline config --provider azdo
+```
+
+If you change your `azd` environment variables at any time (via `azd env set` or as a result of provisioning), re-run that command in order to update the GitHub Actions secrets.

docs/appservice.md

@@ -129,7 +129,7 @@ If the problem is with Azure AI Search (step 2 above), the first step is to chec
 
 You can change many of the search parameters in the "Developer settings" in the frontend and see if results improve for your queries. The most relevant options:
 
-![Screenshot of search options in developer settings](screenshot_searchoptions.png)
+![Screenshot of search options in developer settings](images/screenshot_searchoptions.png)
 
 #### Configuring parameters in the Azure Portal
 
@@ -159,7 +159,7 @@ You can also use the `highlight` parameter to see what text is being matched in
 }
 ```
 
-![Screenshot of search explorer with highlighted results](screenshot_searchindex.png)
+![Screenshot of search explorer with highlighted results](images/screenshot_searchindex.png)
 
 The search explorer works well for testing text, but is harder to use with vectors, since you'd also need to compute the vector embedding and send it in. It is probably easier to use the app frontend for testing vectors/hybrid search.
 

docs/azd.md

@@ -7,15 +7,15 @@ This guide provides more details for using the `prepdocs` script to index docume
   - [Indexing additional documents](#indexing-additional-documents)
   - [Removing documents](#removing-documents)
 - [Overview of Integrated Vectorization](#overview-of-integrated-vectorization)
-  - [Indexing additional documents](#indexing-additional-documents-1)
-  - [Removing documents](#removing-documents-1)
+  - [Indexing of additional documents](#indexing-of-additional-documents)
+  - [Removal of documents](#removal-of-documents)
   - [Scheduled indexing](#scheduled-indexing)
 
 ## Overview of the manual indexing process
 
 The `scripts/prepdocs.py` script is responsible for both uploading and indexing documents. The typical usage is to call it using `scripts/prepdocs.sh` (Mac/Linux) or `scripts/prepdocs.ps1` (Windows), as these scripts will set up a Python virtual environment and pass in the required parameters based on the current `azd` environment. Whenever `azd up` or `azd provision` is run, the script is called automatically.
 
-![Diagram of the indexing process](diagram_prepdocs.png)
+![Diagram of the indexing process](images/diagram_prepdocs.png)
 
 The script uses the following steps to index documents:
 
@@ -64,7 +64,7 @@ To add additional documents to the index, first upload them to your data source
 Then navigate to the Azure portal, find the index, and run it.
 The Azure AI Search indexer will identify the new documents and ingest them into the index.
 
-### Removing documents
+### Removal of documents
 
 To remove documents from the index, remove them from your data source (Blob storage, by default).
 Then navigate to the Azure portal, find the index, and run it.

docs/customization.md

@@ -1,4 +1,4 @@
-# Enabling GPT-4 Turbo with Vision
+# Using GPT-4 Turbo with Vision
 
 This repository now includes an example of integrating GPT-4 Turbo with Vision with Azure AI Search. This feature enables indexing and searching images and graphs, such as financial documents, in addition to text-based content.
 
@@ -14,7 +14,7 @@ This repository now includes an example of integrating GPT-4 Turbo with Vision w
 ### Prerequisites
 
 - Create a [Computer Vision account in Azure Portal first](https://ms.portal.azure.com/#create/Microsoft.CognitiveServicesComputerVision), so that you can agree to the Responsible AI terms for that resource. You can delete that account after agreeing.
-- The ability to deploy a GPT-4 Turbo with Vision model in the [supported regions](https://learn.microsoft.com/azure/ai-services/openai/concepts/models#gpt-4-and-gpt-4-turbo-preview-model-availability). If you're not sure, try to create a deployment from your Azure OpenAI deployments page. You should be able to select: 
+- The ability to deploy a GPT-4 Turbo with Vision model in the [supported regions](https://learn.microsoft.com/azure/ai-services/openai/concepts/models#gpt-4-and-gpt-4-turbo-preview-model-availability). If you're not sure, try to create a deployment from your Azure OpenAI deployments page. You should be able to select:
 
    | Model | Version |
    |--|--|
@@ -25,7 +25,7 @@ This repository now includes an example of integrating GPT-4 Turbo with Vision w
         - gpt-35-turbo
         - text-embedding-ada-002
         - gpt-4v
-    - [Azure AI Vision](https://learn.microsoft.com/en-us/azure/ai-services/computer-vision/)
+    - [Azure AI Vision](https://learn.microsoft.com/azure/ai-services/computer-vision/)
 
 ### Setup and Usage
 
@@ -43,7 +43,7 @@ This repository now includes an example of integrating GPT-4 Turbo with Vision w
 
 
 5. **Web Application Usage:**
-    ![GPT4V configuration screenshot](./gpt4v.png)
+    ![GPT4V configuration screenshot](./images/gpt4v.png)
    - Access the developer options in the web app and select "Use GPT-4 Turbo with Vision".
    - Sample questions will be updated for testing.
    - Interact with the questions to view responses.