Merge pull request #169 from ks6088ts-labs/feature/issue-85_add-docs-site

ks6088ts · web-flow · commit 299d1dcf4b10 · 2024-10-11T17:30:55.000+09:00
add docs on GitHub Pages
diff --git a/.github/workflows/github-pages.yaml b/.github/workflows/github-pages.yaml
@@ -0,0 +1,28 @@
+name: github-pages
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force
diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml
@@ -16,7 +16,8 @@ jobs:
         platform:
           - "ubuntu-latest"
           - "macos-latest"
-          - "windows-latest"
+          # FIXME: "windows-latest" is not supported for now
+          # - "windows-latest"
         python-version:
           - "3.10"
     runs-on: ${{ matrix.platform }}
diff --git a/Makefile b/Makefile
@@ -80,3 +80,18 @@ docker-scan: ## scan Docker image
 
 .PHONY: ci-test-docker
 ci-test-docker: docker-lint docker-build docker-run ## run CI test for Docker
+
+# ---
+# Docs
+# ---
+
+.PHONY: docs
+docs: ## build documentation
+	poetry run mkdocs build
+
+.PHONY: docs-serve
+docs-serve: ## serve documentation
+	poetry run mkdocs serve
+
+.PHONY: ci-test-docs
+ci-test-docs: docs ## run CI test for documentation
diff --git a/README.md b/README.md
@@ -2,6 +2,7 @@
 [![docker](https://github.com/ks6088ts-labs/workshop-azure-openai/actions/workflows/docker.yaml/badge.svg?branch=main)](https://github.com/ks6088ts-labs/workshop-azure-openai/actions/workflows/docker.yaml?query=branch%3Amain)
 [![docker-release](https://github.com/ks6088ts-labs/workshop-azure-openai/actions/workflows/docker-release.yaml/badge.svg)](https://github.com/ks6088ts-labs/workshop-azure-openai/actions/workflows/docker-release.yaml)
 [![ghcr](https://github.com/ks6088ts-labs/workshop-azure-openai/actions/workflows/ghcr.yaml/badge.svg)](https://github.com/ks6088ts-labs/workshop-azure-openai/actions/workflows/ghcr.yaml)
+[![docs](https://github.com/ks6088ts-labs/workshop-azure-openai/actions/workflows/github-pages.yaml/badge.svg)](https://github.com/ks6088ts-labs/workshop-azure-openai/actions/workflows/github-pages.yaml)
 
 <!-- https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/deploy-to-azure-button -->
 
diff --git a/docs/apps/10_streamlit_batch_transcription.md b/docs/apps/10_streamlit_batch_transcription.md
@@ -1,4 +1,4 @@
-# Call Batch Transcription API with Streamlit
+# 10. Call Batch Transcription API with Streamlit
 
 This is a Streamlit app that calls Azure AI Speech Batch Transcription API.
 
@@ -36,7 +36,7 @@ $ python -m streamlit run apps/10_streamlit_batch_transcription/main.py
 
 ### Example
 
-![Streamlit](../../docs/images/10_streamlit_batch_transcription.main.png)
+![Streamlit](../images/10_streamlit_batch_transcription.main.png)
 
 ## References
 
diff --git a/docs/apps/11_promptflow.md b/docs/apps/11_promptflow.md
@@ -1,4 +1,4 @@
-# Getting Started with Prompt flow
+# 11. Getting Started with Prompt flow
 
 This application explains how to get started with [Prompt flow](https://github.com/microsoft/promptflow), a Python library that provides a simple and easy way to build conversational AI applications.
 
diff --git a/docs/apps/12_langgraph_agent.md b/docs/apps/12_langgraph_agent.md
@@ -1,4 +1,4 @@
-# Create agents with LangGraph
+# 12. Create agents with LangGraph
 
 This app demonstrates how to implement agents with LangGraph.
 
@@ -49,7 +49,7 @@ python apps/12_langgraph_agent/advanced_rag_flows/ingestion.py
 python apps/12_langgraph_agent/advanced_rag_flows/main.py
 ```
 
-![Advanced RAG Flows](../../docs/images/12_langgraph_agent_graph.png)
+![Advanced RAG Flows](../images/12_langgraph_agent_graph.png)
 
 ## References
 
diff --git a/docs/apps/13_langchain_toolkits.md b/docs/apps/13_langchain_toolkits.md
@@ -1,4 +1,4 @@
-# LangChain Toolkits sample applications
+# 13. LangChain Toolkits sample applications
 
 This app demonstrates how to use LangChain Toolkits.
 
diff --git a/docs/apps/14_streamlit_azure_ai_speech.md b/docs/apps/14_streamlit_azure_ai_speech.md
@@ -1,4 +1,4 @@
-# Realtime transcription with Azure AI Speech Service
+# 14. Realtime transcription with Azure AI Speech Service
 
 This app demonstrates how to use Azure AI Speech Service for realtime transcription.
 
diff --git a/docs/apps/15_streamlit_chat_slm.md b/docs/apps/15_streamlit_chat_slm.md
@@ -1,4 +1,4 @@
-# Streamlit Chat with SLM
+# 15. Streamlit Chat with SLM
 
 ## Overview
 
diff --git a/docs/apps/16_whisper_transcription.md b/docs/apps/16_whisper_transcription.md
@@ -1,4 +1,6 @@
-# References
+# 16. Whisper transcription
+
+## References
 
 - [openai/whisper](https://github.com/openai/whisper)
 - [Improve --model argument handling and help message #1764](https://github.com/openai/whisper/pull/1764)
diff --git a/docs/apps/1_call_azure_openai_chat.md b/docs/apps/1_call_azure_openai_chat.md
@@ -1,4 +1,4 @@
-# Call Azure OpenAI Service API from Python
+# 1. Call Azure OpenAI Service API from Python
 
 This app demonstrates how to call the Azure OpenAI Service API from Python.
 
diff --git a/docs/apps/2_streamlit_chat.md b/docs/apps/2_streamlit_chat.md
@@ -1,4 +1,4 @@
-# Create an Azure OpenAI Chat app using Streamlit
+# 2. Create an Azure OpenAI Chat app using Streamlit
 
 This app demonstrates how to create a chat application using Azure OpenAI Service and Streamlit.
 
@@ -108,11 +108,11 @@ $ python -m streamlit run apps/2_streamlit_chat/main.py
 
 When you access `http://localhost:8501`, you will see the following screen.
 
-![Streamlit Chat](../../docs/images/2_streamlit_chat.initial_page.png)
+![Streamlit Chat](../images/2_streamlit_chat.initial_page.png)
 
 To start a conversation, fill in the required fields in the sidebar and you will see the following screen.
 
-![Streamlit Chat](../../docs/images/2_streamlit_chat.chat_page.png)
+![Streamlit Chat](../images/2_streamlit_chat.chat_page.png)
 
 ## Note
 
diff --git a/docs/apps/3_call_azure_cosmos_db.md b/docs/apps/3_call_azure_cosmos_db.md
@@ -1,4 +1,4 @@
-# Call Azure Cosmos DB from Python
+# 3. Call Azure Cosmos DB from Python
 
 This app demonstrates how to call Azure Cosmos DB from Python.
 
diff --git a/docs/apps/4_streamlit_chat_history.md b/docs/apps/4_streamlit_chat_history.md
@@ -1,4 +1,4 @@
-# Add feature to store chat history using Azure Cosmos DB
+# 4. Add feature to store chat history using Azure Cosmos DB
 
 This app demonstrates how to add a feature to save chat history using Azure Cosmos DB to an Azure OpenAI Chat app using Streamlit implemented in [2_streamlit_chat](../2_streamlit_chat/).
 
@@ -36,11 +36,11 @@ Access `http://localhost:8501` and set the required fields in the sidebar to sta
 
 When you send a message, the chat history will be saved in Azure Cosmos DB.
 
-![Chat page](../../docs/images/4_streamlit_chat_history.chat_page.png)
+![Chat page](../images/4_streamlit_chat_history.chat_page.png)
 
 Conversation history can be viewed from the Cosmos DB Data Explorer as shown below.
 
-![Cosmos DB Data Explorer](../../docs/images/4_streamlit_chat_history.data_explorer.png)
+![Cosmos DB Data Explorer](../images/4_streamlit_chat_history.data_explorer.png)
 
 The chat history is saved as shown below.
 
diff --git a/docs/apps/5_streamlit_query_chat_history.md b/docs/apps/5_streamlit_query_chat_history.md
@@ -1,4 +1,4 @@
-# Search Chat History
+# 5. Search Chat History
 
 This application is used to search the chat history accumulated in [4_streamlit_chat_history](../4_streamlit_chat_history/).
 
@@ -34,4 +34,4 @@ Access `http://localhost:8501` and set the required fields in the sidebar to sea
 
 When you click the "Search" button, the chat history will be displayed.
 
-![Main page](../../docs/images/5_streamlit_query_chat_history.main.png)
+![Main page](../images/5_streamlit_query_chat_history.main.png)
diff --git a/docs/apps/6_call_azure_ai_search.md b/docs/apps/6_call_azure_ai_search.md
@@ -1,4 +1,4 @@
-# Call Azure AI Search from Python
+# 6. Call Azure AI Search from Python
 
 This application explains how to call Azure AI Search from Python.
 
@@ -50,8 +50,7 @@ So we introduce `RecursiveCharacterTextSplitter` which provides a simple and eas
 1. Set credentials in `.env`
 1. Run scripts in the [apps/6_call_azure_ai_search](./) directory
 
-> [!CAUTION]
-> `AZURE_AI_SEARCH_INDEX_NAME` in `.env` should be unique and should not be changed once set.
+> [!CAUTION] > `AZURE_AI_SEARCH_INDEX_NAME` in `.env` should be unique and should not be changed once set.
 > If you change the index name, you will need to recreate the index and re-upload the documents.
 
 Set up the environment and install dependencies:
diff --git a/docs/apps/7_streamlit_chat_rag.md b/docs/apps/7_streamlit_chat_rag.md
@@ -1,4 +1,4 @@
-# Add RAG feature to Streamlit chat app
+# 7. Add RAG feature to Streamlit chat app
 
 This app demonstrates how to add the Retrieval-Augmented Generation (RAG) feature to a Streamlit chat app.
 
@@ -64,7 +64,7 @@ Access `http://localhost:8501` and set the required fields in the sidebar to sta
 
 When you send a question about Contoso Corporation, the chatbot will respond with an answer from Azure AI Search.
 
-![RAG Chat](../../docs/images/7_streamlit_chat_rag.main.png)
+![RAG Chat](../images/7_streamlit_chat_rag.main.png)
 
 To see how the RAG feature works, watch the video below.
 
diff --git a/docs/apps/8_streamlit_azure_openai_batch.md b/docs/apps/8_streamlit_azure_openai_batch.md
@@ -1,4 +1,4 @@
-# Call Azure OpenAI Batch API with Streamlit
+# 8. Call Azure OpenAI Batch API with Streamlit
 
 This app demonstrates how to call Azure OpenAI Batch API with Streamlit.
 
@@ -30,7 +30,7 @@ $ python -m streamlit run apps/8_streamlit_azure_openai_batch/main.py
 
 ### Example
 
-![Streamlit Chat](../../docs/images/8_streamlit_azure_openai_batch.main.png)
+![Streamlit Chat](../images/8_streamlit_azure_openai_batch.main.png)
 
 ## References
 
diff --git a/docs/apps/99_streamlit_examples.md b/docs/apps/99_streamlit_examples.md
@@ -1,4 +1,4 @@
-# Code samples for Streamlit
+# 99. Code samples for Streamlit
 
 This app includes code samples for Streamlit. You can run the app and select the sample you want to run from the sidebar.
 
@@ -35,51 +35,51 @@ Access to http://localhost:8501 and select the sample you want to run from the s
 
 #### 1. File Q&A
 
-![File Q&A](../../docs/images/99_streamlit_examples.fileqa.png)
+![File Q&A](../images/99_streamlit_examples.fileqa.png)
 
 #### 2. Image Q&A
 
-![Image Q&A](../../docs/images/99_streamlit_examples.imageqa.png)
+![Image Q&A](../images/99_streamlit_examples.imageqa.png)
 
 #### 3. Camera Q&A
 
-![Camera Q&A](../../docs/images/99_streamlit_examples.cameraqa.png)
+![Camera Q&A](../images/99_streamlit_examples.cameraqa.png)
 
 #### 4. Translate text
 
-![Translate text](../../docs/images/99_streamlit_examples.translate.png)
+![Translate text](../images/99_streamlit_examples.translate.png)
 
 #### 5. Explain data
 
-![Explain data](../../docs/images/99_streamlit_examples.explaindata.png)
+![Explain data](../images/99_streamlit_examples.explaindata.png)
 
 #### 6. Speech to Text
 
-![Speech to Text](../../docs/images/99_streamlit_examples.stt.png)
+![Speech to Text](../images/99_streamlit_examples.stt.png)
 
 #### 7. Text to Speech
 
-![Text to Speech](../../docs/images/99_streamlit_examples.tts.png)
+![Text to Speech](../images/99_streamlit_examples.tts.png)
 
 #### 8. Create image
 
-![Create image](../../docs/images/99_streamlit_examples.createimage.png)
+![Create image](../images/99_streamlit_examples.createimage.png)
 
 #### 9. Visualize location
 
-![Visualize location](../../docs/images/99_streamlit_examples.map.png)
+![Visualize location](../images/99_streamlit_examples.map.png)
 
 #### 10. Object detection
 
-![Object detection](../../docs/images/99_streamlit_examples.objectdetection.png)
+![Object detection](../images/99_streamlit_examples.objectdetection.png)
 
 #### 11. Pose estimation
 
-![Pose estimation](../../docs/images/99_streamlit_examples.poseestimation.png)
+![Pose estimation](../images/99_streamlit_examples.poseestimation.png)
 
 #### 12. Video processing
 
-![Video processing](../../docs/images/99_streamlit_examples.videoprocessing.png)
+![Video processing](../images/99_streamlit_examples.videoprocessing.png)
 
 ref. [data-videos/traffic.mp4](https://github.com/OlafenwaMoses/ImageAI/blob/master/data-videos/traffic.mp4)
 
diff --git a/docs/apps/9_streamlit_azure_document_intelligence.md b/docs/apps/9_streamlit_azure_document_intelligence.md
@@ -1,4 +1,4 @@
-# Call Azure Document Intelligence API with Streamlit
+# 9. Call Azure Document Intelligence API with Streamlit
 
 This Streamlit app demonstrates how to call Azure Document Intelligence API with Streamlit.
 
@@ -30,7 +30,7 @@ $ python -m streamlit run apps/9_streamlit_azure_document_intelligence/main.py
 
 ### Example
 
-![Streamlit Chat](../../docs/images/9_streamlit_azure_document_intelligence.main.png)
+![Streamlit Chat](../images/9_streamlit_azure_document_intelligence.main.png)
 
 ## References
 
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,17 @@
+# Welcome to MkDocs
+
+For full documentation visit [mkdocs.org](https://www.mkdocs.org).
+
+## Commands
+
+* `mkdocs new [dir-name]` - Create a new project.
+* `mkdocs serve` - Start the live-reloading docs server.
+* `mkdocs build` - Build the documentation site.
+* `mkdocs -h` - Print help message and exit.
+
+## Project layout
+
+    mkdocs.yml    # The configuration file.
+    docs/
+        index.md  # The documentation homepage.
+        ...       # Other markdown pages, images and other files.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -0,0 +1,46 @@
+# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json
+site_name: Workshop for Azure OpenAI Service
+site_url: ""
+nav:
+  - Home: index.md
+  - Applications:
+    - 1. Call Azure OpenAI Service API from Python: apps/1_call_azure_openai_chat.md
+    - 2. Create an Azure OpenAI Chat app using Streamlit: apps/2_streamlit_chat.md
+    - 3. Call Azure Cosmos DB from Python: apps/3_call_azure_cosmos_db.md
+    - 4. Add feature to store chat history using Azure Cosmos DB: apps/4_streamlit_chat_history.md
+    - 5. Search Chat History: apps/5_streamlit_query_chat_history.md
+    - 6. Call Azure AI Search from Python: apps/6_call_azure_ai_search.md
+    - 7. Add RAG feature to Streamlit chat app: apps/7_streamlit_chat_rag.md
+    - 8. Call Azure OpenAI Batch API with Streamlit: apps/8_streamlit_azure_openai_batch.md
+    - 9. Call Azure Document Intelligence API with Streamlit: apps/9_streamlit_azure_document_intelligence.md
+    - 10. Call Batch Transcription API with Streamlit: apps/10_streamlit_batch_transcription.md
+    - 11. Getting Started with Prompt flow: apps/11_promptflow.md
+    - 12. Create agents with LangGraph: apps/12_langgraph_agent.md
+    - 13. LangChain Toolkits sample applications: apps/13_langchain_toolkits.md
+    - 14. Realtime transcription with Azure AI Speech Service: apps/14_streamlit_azure_ai_speech.md
+    - 15. Streamlit Chat with SLM: apps/15_streamlit_chat_slm.md
+    - 16. Whisper transcription: apps/16_whisper_transcription.md
+    - 99. Code samples for Streamlit: apps/99_streamlit_examples.md
+theme:
+  name: material
+  # https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#automatic-light-dark-mode
+  palette:
+    # Palette toggle for automatic mode
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Getting Started with Prompt flow`
	`1`	`+# 11. Getting Started with Prompt flow`
`2`	`2`
`3`	`3`	`This application explains how to get started with [Prompt flow](https://github.com/microsoft/promptflow), a Python library that provides a simple and easy way to build conversational AI applications.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# LangChain Toolkits sample applications`
	`1`	`+# 13. LangChain Toolkits sample applications`
`2`	`2`
`3`	`3`	`This app demonstrates how to use LangChain Toolkits.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Realtime transcription with Azure AI Speech Service`
	`1`	`+# 14. Realtime transcription with Azure AI Speech Service`
`2`	`2`
`3`	`3`	`This app demonstrates how to use Azure AI Speech Service for realtime transcription.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Streamlit Chat with SLM`
	`1`	`+# 15. Streamlit Chat with SLM`
`2`	`2`
`3`	`3`	`## Overview`
`4`	`4`