Merge pull request #20 from skytin1004/update

Update README.md and CONTRIBUTING.md with Quick Install instructions and reorganize sections
Azure · Sep 29, 2024 · 1df321d · 1df321d
2 parents 7d9c49c + a998f4f
commit 1df321d
Show file tree

Hide file tree

Showing 6 changed files with 68 additions and 47 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -61,6 +61,33 @@ poetry install
 1. Create an `.env` file in the root directory by copying the provided `.env.template` file.
 1. Fill in the environment variables as guided.
 
+> [!TIP]
+>
+> ### Additional development environment options
+>
+> In addition to running the project locally, you can also use GitHub Codespaces or VS Code Dev Containers for an alternative development environment setup.
+>
+> #### GitHub Codespaces
+>
+> You can run this samples virtually by using GitHub Codespaces and no additional settings or setup are required. 
+>
+> The button will open a web-based VS Code instance in your browser:
+>
+> 1. Open the template (this may take several minutes):
+>
+>     [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/azure/co-op-translator)
+>
+> #### Running Locally using VS Code Dev Containers
+>
+> ⚠️ This option will only work if your Docker Desktop is allocated at least 16 GB of RAM. If you have less than 16 GB of RAM, you can try the [GitHub Codespaces option](#github-codespaces) or [set it up locally](#development-environment-setup).
+>
+> A related option is 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)
+> 2. Open the project:
+>
+>    [![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/azure/co-op-translator)
+
 ## Running Co Op Translator
 
 To run Co Op Translator using Poetry in your environment, follow these steps:
@@ -75,4 +102,3 @@ To run Co Op Translator using Poetry in your environment, follow these steps:
 
 > [!NOTE]
 > Ensure your Poetry environment is activated (poetry shell) before running the command.
-
diff --git a/README.md b/README.md
@@ -14,6 +14,7 @@ _Easily automate multilingual translations for your projects with co-op-translat
 [![GitHub stars](https://img.shields.io/github/stars/azure/co-op-translator?style=social&label=Star)](https://GitHub.com/azure/co-op-translator/stargazers/)
 
 [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/azure/co-op-translator)
+[![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/azure/co-op-translator)
 
 ## Overview
 
@@ -45,57 +46,48 @@ Here is an example of how Co Op Translator can be used to translate text in imag
 - **Automation**: Automates the translation process, reducing manual effort and increasing consistency.
 - **Integration**: Easily integrates with existing projects, providing a seamless translation experience.
 
-## Environment setup
-
-### GitHub Codespaces
-
-You can run this samples virtually by using GitHub Codespaces and no additional settings or setup are required. 
-
-The button will open a web-based VS Code instance in your browser:
-
-1. Open the template (this may take several minutes):
+### Repository structure
 
-    [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/azure/co-op-translator)
+- **data/**: Contains data files.
+- **notebooks/**: Jupyter notebooks for examples and tutorials.
+- **src/co_op_translator/**: Source code for the translator.
+- **tests/**: Test cases for the project.
 
-### Running Locally using VS Code Dev Containers
+## Getting started with Co Op Translator
 
-⚠️ This option will only work if your Docker Desktop is allocated at least 16 GB of RAM. If you have less than 16 GB of RAM, you can try the [GitHub Codespaces option](#github-codespaces) or [set it up locally](#local-environment).
+### Prerequisites
 
-A related option is 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):
+- Azure Computer vision resource
+- Azure OpenAI resource
+- Python 3.10 or higher
 
-1. Start Docker Desktop (install it if not already installed)
-2. Open the project:
+### Quick install
 
-    [![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/azure/co-op-translator)
+#### Install Co Op Translator via pip
 
-### Repository structure
+```bash
+pip install co-op-translator
+```
 
-- **data/**: Contains data files.
-- **notebooks/**: Jupyter notebooks for examples and tutorials.
-- **src/co_op_translator/**: Source code for the translator.
-- **tests/**: Test cases for the project.
+#### Install Co Op Translator via poetry
 
-## Getting started with Co Op Translator
+```bash
+poetry add co-op-translator
+```
 
 ### How to use Co Op Translator
 
-1. [Set up Azure resources before starting](./docs/set-up-azure-resources.md)
-1. [Create an '.env' file in the root directory](./docs/create-env-file.md)
-1. [Install the Co Op translator package](./docs/install-package.md)
-1. [Use Co Op translator in your project](./docs/use-co-op-translator.md)
+1. [Set up Azure resources before starting](./getting_started/set-up-azure-resources.md)
+1. [Create an '.env' file in the root directory](./getting_started/create-env-file.md)
+1. [Install the Co Op translator package](./getting_started/install-package.md)
+1. [Use Co Op translator in your project](./getting_started/use-co-op-translator.md)
 
-### Sample Notebooks(Update in progress)
+### Sample notebooks (update in progress)
 
 - [**Getting Started with notebook: basic version**](./notebooks/notebook_for_testing.ipynb)
 - [**Getting Started with notebook: module version**](./notebooks/notebook_for_library.ipynb)
 
-### Prerequisites
-
-- Azure AI Services resource
-- Azure OpenAI resource
-- Python 3.10 or higher
-
-## Supported Languages
+## Supported languages
 
 The table below lists the languages currently supported by **Co Op Translator**. It includes language codes, language names, and any known issues associated with each language. If you would like to add support for a new language, please add the corresponding language code, name, and appropriate font in the `font_language_mappings.yml` file located at `src/co_op_translator/fonts/` and submit a pull request after testing.
 
@@ -146,7 +138,7 @@ The table below lists the languages currently supported by **Co Op Translator**.
 | hr            | Croatian             | NotoSans-Medium.ttf               | No          | No           |
 | sl            | Slovenian            | NotoSans-Medium.ttf               | No          | No           |
 
-### Adding a New Language
+### Adding a new language
 
 To add support for a new language:
 
@@ -165,6 +157,20 @@ new_lang:
   rtl: false
 ```
 
+## Contributing
+
+This project welcomes contributions and suggestions. Interested in contributing to Azure Co Op Translator? Please see our [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on how you can help make Co Op Translator more accessible.
+
+## Contributors
+
+[![co-op-translator contributors](https://contrib.rocks/image?repo=Azure/co-op-translator)](https://github.com/Azure/co-op-translator/graphs/contributors)
+
+## Code of Conduct
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
+contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
 ## Responsible AI
 
 Microsoft is committed to helping our customers use our AI products responsibly, sharing our learnings, and building trust-based partnerships through tools like Transparency Notes and Impact Assessments. Many of these resources can be found at [https://aka.ms/RAI](https://aka.ms/RAI).
@@ -178,16 +184,6 @@ Another aspect to take into account is the overall application performance. With
 
 You can evaluate your AI application in your development environment using the [prompt flow SDK](https://microsoft.github.io/promptflow/index.html). Given either a test dataset or a target, your generative AI application generations are quantitatively measured with built-in evaluators or custom evaluators of your choice. To get started with the prompt flow sdk to evaluate your system, you can follow the [quickstart guide](https://learn.microsoft.com/azure/ai-studio/how-to/develop/flow-evaluate-sdk). Once you execute an evaluation run, you can [visualize the results in Azure AI Studio](https://learn.microsoft.com/azure/ai-studio/how-to/evaluate-flow-results).
 
-## Contributing
-
-This project welcomes contributions and suggestions. Interested in contributing to Azure Co Op Translator? Please see our [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on how you can help make Co Op Translator more accessible.
-
-## Code of Conduct
-
-This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
-For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
-contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
-
 ## Trademarks
 
 This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft 

diff --git a/docs/create-env-file.md → getting_started/create-env-file.md b/docs/create-env-file.md → getting_started/create-env-file.md
diff --git a/docs/install-package.md → getting_started/install-package.md b/docs/install-package.md → getting_started/install-package.md
diff --git a/docs/set-up-azure-resources.md → getting_started/set-up-azure-resources.md b/docs/set-up-azure-resources.md → getting_started/set-up-azure-resources.md
diff --git a/docs/use-co-op-translator.md → getting_started/use-co-op-translator.md b/docs/use-co-op-translator.md → getting_started/use-co-op-translator.md
@@ -119,7 +119,6 @@ If you want to translate the project into all supported languages, use the all k
 > [!WARNING]
 > Translating all languages at once can take a significant amount of time depending on the project size. For example, translating the Phi-3 CookBook into Spanish took about 1 hour and 25-30 minutes. Given the scale, it's not practical for one person to handle 20 languages. It's recommended to split the work among multiple contributors, each managing one or two languages, and update translations gradually.
 
-
 ```bash
 translate -l "all"
 ```
-Original file line number
+Diff line change
@@ Expand Up @@
     > [!WARNING]
     > Translating all languages at once can take a significant amount of time depending on the project size. For example, translating the Phi-3 CookBook into Spanish took about 1 hour and 25-30 minutes. Given the scale, it's not practical for one person to handle 20 languages. It's recommended to split the work among multiple contributors, each managing one or two languages, and update translations gradually.
     ```bash
     translate -l "all"
     ```
@@ Expand Down @@