[Doc & sample] Refine deploy docs & samples (microsoft#280)

# Description

Please add an informative description that covers that changes made by
the pull request and link all relevant issues.

# All Promptflow Contribution checklist:
- [ ] **The pull request does not introduce [breaking changes]**
- [ ] **CHANGELOG is updated for new features, bug fixes or other
significant changes.**
- [ ] **I have read the [contribution guidelines](../CONTRIBUTING.md).**

## General Guidelines and Best Practices
- [ ] Title of the pull request is clear and informative.
- [ ] There are a small number of commits, each of which have an
informative message. This means that previously merged commits do not
appear in the history of the PR. For more information on cleaning up the
commits in your PR, [see this
page](https://github.com/Azure/azure-powershell/blob/master/documentation/development-docs/cleaning-up-commits.md).

### Testing Guidelines
- [ ] Pull request includes test coverage for the included changes.

---------

Signed-off-by: Brynn Yin <[email protected]>
Co-authored-by: Clement Wang <[email protected]>
Co-authored-by: Clement Wang <[email protected]>

README.md

@@ -23,7 +23,7 @@ With prompt flow, you will be able to:
 ## Get Started with Prompt flow ⚡
 
 Develop your LLM apps with Prompt flow: please start with our [docs](https://microsoft.github.io/promptflow) & [examples](./examples/README.md):
-- [Getting Started with Prompt Flow](https://github.com/microsoft/promptflow/blob/main/examples/tutorials/get-started/quickstart.ipynb): A step by step guidance to invoke your first flow run.
+- [Getting Started with Prompt Flow](https://microsoft.github.io/promptflow/how-to-guides/quick-start.html): A step by step guidance to invoke your first flow run.
 - [Tutorial: Chat with PDF](https://github.com/microsoft/promptflow/blob/main/examples/tutorials/e2e-development/chat-with-pdf.md): An end-to-end tutorial on how to build a high quality chat application with prompt flow, including flow development and evaluation with metrics.
 
 Contribute to Prompt flow: please start with our dev setup guide: [dev_setup.md](./docs/dev/dev_setup.md).

docs/cloud/azureai/deploy-to-azure-appservice.md

@@ -1,24 +1,81 @@
 # Deploy to Azure App Service
 
 [Azure App Service](https://learn.microsoft.com/azure/app-service/) is an HTTP-based service for hosting web applications, REST APIs, and mobile back ends.
-Promptflow has provided scripts (`deploy.sh` for bash and `deploy.ps1` for powershell) to help deploy the docker image to Azure App Service.
+The scripts (`deploy.sh` for bash and `deploy.ps1` for powershell) under [this folder](https://github.com/microsoft/promptflow/tree/main/examples/tutorials/flow-deploy/azure-app-service) are here to help deploy the docker image to Azure App Service.
+
+This example demos how to deploy [web-classification](https://github.com/microsoft/promptflow/tree/main/examples/flows/standard/web-classification/) deploy a flow using Azure App Service.
+
+## Build a flow as docker format app
+
+Use the command below to build a flow as docker format app:
 
-Example command to use bash script:
 ```bash
-bash deploy.sh -i <image_tag> -r "promptflow.azurecr.io" -g <resource_group>
+pf flow build --source ../../flows/standard/web-classification --output build --format docker
 ```
 
+Note that all dependent connections must be created before building as docker.
+
+## Deploy with Azure App Service
+The two scripts will do the following things:
+1. Create a resource group if not exists.
+2. Build and push the image to docker registry.
+3. Create an app service plan with the give sku.
+4. Create an app with specified name, set the deployment container image to the pushed docker image.
+5. Set up the environment variables for the app.
+
+::::{tab-set}
+:::{tab-item} Bash
+Example command to use bash script:
+```shell
+bash deploy.sh --path build -i <image_tag> --name my_app_23d8m -r <docker registery> -g <resource_group>
+```
+See the full parameters by `bash deploy.sh -h`.
+:::
+:::{tab-item} PowerShell
 Example command to use powershell script:
 ```powershell
-.\deploy.ps1 -i <image_tag> -r "promptflow.azurecr.io" -g <resource_group>
+.\deploy.ps1 -i <image_tag> --Name my_app_23d8m -r <docker registery> -g <resource_group>
 ```
+See the full parameters by `.\deploy.ps1 -h`.
+:::
+::::
+
+Note that the `name` will produce a unique FQDN as AppName.azurewebsites.net.
+
 
-See the full parameters by `bash deploy.sh -h` or `.\deploy.ps1 -h`.
+## View and test the web app
+The web app can be found via [azure portal](https://ms.portal.azure.com/) 
+
+![img](../../media/cloud/azureml/deploy_appservice_azure_portal_img.png)
 
 After the app created, you will need to go to https://ms.portal.azure.com/ find the app and set up the environment variables
 at (Settings>Configuration) or (Settings>Environment variables), then restart the app.
 
+![img](../../media/cloud/azureml/deploy_appservice_set_env_var.png)
+
+The app can be tested by sending a POST request to the endpoint or browse the test page.
+::::{tab-set}
+:::{tab-item} Bash
+```bash
+curl https://<name>.azurewebsites.net/score --data '{"url":"https://play.google.com/store/apps/details?id=com.twitter.android"}' -X POST  -H "Content-Type: application/json"
+```
+:::
+:::{tab-item} PowerShell
+```powershell
+Invoke-WebRequest -URI https://<name>.azurewebsites.net/score -Body '{"url":"https://play.google.com/store/apps/details?id=com.twitter.android"}' -Method POST  -ContentType "application/json"
+```
+:::
+:::{tab-item} Test Page
+Browse the app at Overview and see the test page:
+
+![img](../../media/cloud/azureml/deploy_appservice_test_page.png)
+:::
+::::
+
 Tips:
 - Reach deployment logs at (Deployment>Deployment Central) and app logs at (Monitoring>Log stream).
 - Reach advanced deployment tools at https://$name.scm.azurewebsites.net/.
 - Reach more details about app service at https://learn.microsoft.com/azure/app-service/.
+
+## Next steps
+- Try the example [here](https://github.com/microsoft/promptflow/blob/main/examples/tutorials/flow-deploy/azure-app-service).

docs/how-to-guides/deploy-a-flow/deploy-using-dev-server.md

@@ -3,7 +3,7 @@
 This is an experimental feature, and may change at any time. Learn [more](https://aka.ms/azuremlexperimental).
 :::
 
-After create a flow and test it properly, the flow can be served as a http endpoint.
+Once you have created and thoroughly tested a flow, you can use it as an HTTP endpoint.
 
 ::::{tab-set}
 :::{tab-item} CLI
@@ -29,6 +29,7 @@ The expected result is as follows if the flow served successfully, and the proce
 :sync: VSC
 ![img](../../media/how-to-guides/vscode_export.png)
 ![img](../../media/how-to-guides/vscode_export_as_local_app.png)
+![img](../../media/how-to-guides/vscode_start_local_app.png)
 :::
 ::::
 
@@ -46,13 +47,13 @@ You could open another terminal to test the endpoint with the following command:
 Invoke-WebRequest -URI http://localhost:8080/score -Body '{"url":"https://play.google.com/store/apps/details?id=com.twitter.android"}' -Method POST  -ContentType "application/json"
 ```
 :::
-:::{tab-item} VS Code Extension
-:sync: VSC
-![img](../../media/how-to-guides/vscode_start_local_app.png)
+:::{tab-item} Test Page
+The development server has a built-in web page you can use to test the flow. Open 'http://localhost:8080' in your browser.
+![img](../../media/how-to-guides/deploy_flow_test_page.png)
 :::
 ::::
 
 ## Next steps
-- Try the example [here](https://github.com/microsoft/promptflow/blob/main/examples/tutorials/flow-deploy/deploy.md).
+- Try the example [here](https://github.com/microsoft/promptflow/tree/main/examples/flows/standard/web-classification/).
 - See how to [deploy a flow using docker](deploy-using-docker.md).
 - See how to [deploy a flow using kubernetes](deploy-using-kubernetes.md).

docs/how-to-guides/deploy-a-flow/deploy-using-docker.md

@@ -62,7 +62,7 @@ Note that all dependent connections must be created before exporting as docker.
 
 Like other Dockerfile, you need to build the image first. You can tag the image with any name you want. In this example, we use `promptflow-serve`.
 
-After cd to the output directory, run the command below:
+Run the command below to build image:
 
 ```bash
 docker build build -t web-classification-serve
@@ -100,5 +100,5 @@ curl http://localhost:8080/score --data '{"url":"https://play.google.com/store/a
 ```
 
 ## Next steps
-- Try the example [here](https://github.com/microsoft/promptflow/blob/main/examples/tutorials/flow-deploy/deploy.md).
+- Try the example [here](https://github.com/microsoft/promptflow/blob/main/examples/tutorials/flow-deploy/docker).
 - See how to [deploy a flow using kubernetes](deploy-using-kubernetes.md).

docs/how-to-guides/deploy-a-flow/index.md

@@ -1,5 +1,5 @@
 # Deploy a flow
-A flow can be deployed across multiple platforms, such as a local development service, within a Docker container, onto a Kubernetes cluster, etc.
+A flow can be deployed to multiple platforms, such as a local development service, Docker container, Kubernetes cluster, etc.
 
 ```{gallery-grid}
 :grid-columns: 1 2 2 3
@@ -15,12 +15,21 @@ A flow can be deployed across multiple platforms, such as a local development se
   content: "<center><b>Kubernetes</b></center>"
   website: deploy-using-kubernetes.html
  
+```
+
+We also provide guides to deploy to cloud, such as azure app service:
+
+```{gallery-grid}
+:grid-columns: 1 2 2 3
+
 - image: ../../media/how-to-guides/appservice.png
   content: "<center><b>Azure App Service</b></center>"
   website: ../../cloud/azureai/deploy-to-azure-appservice.html
 
 ```
 
+We are working on more official deployment guides for other hosting providers, and welcome user submitted guides.
+
 ```{toctree}
 :maxdepth: 1
 :hidden:

docs/how-to-guides/index.md

@@ -5,7 +5,6 @@ Simple and short articles grouped by topics, each introduces a core feature of p
 ```{toctree}
 :maxdepth: 1
 
-quick-start
 init-and-test-a-flow
 run-and-evaluate-a-flow
 tune-prompts-with-variants

docs/how-to-guides/quick-start.md

@@ -1,4 +1,4 @@
-# Quick start
+# Quick Start
 
 This guide will walk you through the fist step using of prompt flow code-first experience. 
 

docs/index.md

@@ -11,46 +11,45 @@ html_theme.sidebar_secondary.remove: true
 
 With prompt flow, you will be able to: 
 
-- Create executable workflows that link LLMs, prompts, Python code and other tools together. 
-- Debug and iterate your flows, especially the interaction with LLMs with ease.
-- Evaluate your flow's quality and performance with larger datasets.
-- Integrate the testing and evaluation into your CI/CD system to ensure quality of your flow.
-- Deploy your flow to the serving platform you choose or integrate into your app's code base easily.
-- (Optional but highly recommended) Collaborate with your team by leveraging the cloud version of [Prompt flow in Azure AI](https://learn.microsoft.com/en-us/azure/machine-learning/prompt-flow/overview-what-is-prompt-flow?view=azureml-api-2).
+- **Create [flows](./concepts/concept-flows.md)** that link [LLMs](./reference/tools-reference/llm-tool.md), [prompts](./reference/tools-reference/prompt-tool.md), [Python](./reference/tools-reference/python-tool.md) code and other [tools](./concepts/concept-tools.md) together in a executable workflow. 
+- **Debug and iterate your flows**, especially the interaction with LLMs with ease.
+- **Evaluate your flows**, calculate quality and performance metrics with larger datasets.
+- **Integrate the testing and evaluation into your CI/CD system** to ensure quality of your flow.
+- **Deploy your flows** to the serving platform you choose or integrate into your app's code base easily.
+- (Optional but highly recommended) **Collaborate with your team** by leveraging the cloud version of [Prompt flow in Azure AI](https://learn.microsoft.com/en-us/azure/machine-learning/prompt-flow/overview-what-is-prompt-flow?view=azureml-api-2).
 
 > Welcome to join us to make Prompt flow better by
 > participating [discussions](https://github.com/microsoft/promptflow/discussions),
 > opening [issues](https://github.com/microsoft/promptflow/issues/new/choose),
 > submitting [PRs](https://github.com/microsoft/promptflow/pulls).
 
-This documentation site contains guides for prompt flow sdk, cli and vscode extension users.
+This documentation site contains guides for prompt flow [sdk, cli](https://pypi.org/project/promptflow/) and [vscode extension](https://marketplace.visualstudio.com/items?itemName=prompt-flow.prompt-flow) users.
 
 ```{gallery-grid}
 :grid-columns: 1 2 2 2
 - header: "🚀 Quick Start"
   content: "
-    How to develop and run your first prompt flow.<br/><br/>
+    Quick start and end-to-end tutorials.<br/><br/>
     - [Getting started with Prompt flow](how-to-guides/quick-start.md)<br/>
     - [E2E development tutorial: chat with PDF](https://github.com/microsoft/promptflow/blob/main/examples/tutorials/e2e-development/chat-with-pdf.md)<br/>
-    - Learn more: [tutorials & samples](tutorials/index.md)<br/>
+    - Find more: [tutorials & samples](tutorials/index.md)<br/>
   "
 
 - header: "📒 How-to Guides"
   content: "
-    Articles guide different user roles to done a specific task in prompt flow.<br/><br/>
+    Articles guide user to complete a specific task in prompt flow.<br/><br/>
     - [Initialize and test a flow](how-to-guides/init-and-test-a-flow.md)<br/>
     - [Run and evaluate a flow](how-to-guides/run-and-evaluate-a-flow.md)<br/>
     - [Tune prompts using variants](how-to-guides/tune-prompts-with-variants.md)<br/>
     - [Deploy a flow](how-to-guides/deploy-a-flow/index.md)<br/>
   "
 ```
 
-Reach more details about concepts and tools of prompt flow.
 ```{gallery-grid}
 :grid-columns: 1 2 2 2
 - header: "📑 Concepts"
   content: "
-    Introduction of key concepts of the core features of prompt flow.<br/><br/>
+    Introduction of key concepts of prompt flow.<br/><br/>
     - [Flows](concepts/concept-flows.md)<br/>
     - [Tools](concepts/concept-tools.md)<br/>
     - [Connections](concepts/concept-connections.md)<br/>
@@ -59,16 +58,17 @@ Reach more details about concepts and tools of prompt flow.
 
 - header: "🔍 Reference"
   content: "
-    Useful resources & reference link.<br/><br/>
+    Reference provides technical information about prompt flow API.<br/><br/>
     - Command line Interface reference: [pf](reference/pf-command-reference.md)<br/>
+    - Python library reference: [promptflow](reference/python-library-reference/promptflow.md)<br/>
     - Tool reference: [LLM Tool](reference/tools-reference/llm-tool.md), [Python Tool](reference/tools-reference/python-tool.md), [Prompt Tool](reference/tools-reference/prompt-tool.md)<br/>
   "
 ```
 
 ```{toctree}
 :hidden:
-:maxdepth: 2
-concepts/index
+:maxdepth: 1
+how-to-guides/quick-start
 ```
 
 ```{toctree}
@@ -83,6 +83,12 @@ how-to-guides/index
 tutorials/index
 ```
 
+```{toctree}
+:hidden:
+:maxdepth: 2
+concepts/index
+```
+
 ```{toctree}
 :hidden:
 :maxdepth: 1

docs/tutorials/index.md

@@ -9,7 +9,7 @@ This section contains a collection of flow samples and step-by-step tutorials.
 |SDK|[Chat with PDF - test, evaluation and experimentation](https://github.com/microsoft/promptflow/blob/main/examples/flows/chat/chat-with-pdf/chat-with-pdf.ipynb)| We will walk you through how to use prompt flow Python SDK to test, evaluate and experiment with the "Chat with PDF" flow.
 |SDK|[Connection management](https://github.com/microsoft/promptflow/blob/main/examples/connections/connection.ipynb)| Manage various types of connections using sdk
 |CLI|[Working with connection](https://github.com/microsoft/promptflow/blob/main/examples/connections/README.md)| Manage various types of connections using cli
-|SDK|[Run prompt flow in Azure AI](https://github.com/microsoft/promptflow/blob/main/examples/tutorials/get-started/quickstart-azure.ipynb)| A quickstart tutorial to run a flow in Azure AI and evaluate it.
+|SDK|[Run prompt flow in Azure AI](https://github.com/microsoft/promptflow/blob/main/examples/tutorials/get-started/quickstart-azure.ipynb)| A quick start tutorial to run a flow in Azure AI and evaluate it.
 |SDK|[Flow run management in Azure AI](https://github.com/microsoft/promptflow/blob/main/examples/tutorials/run-management/cloud-run-management.ipynb)| Flow run management in azure AI