From 96ac960663391285fbdbe5c7e7d07feb8990f0b5 Mon Sep 17 00:00:00 2001 From: Seth Falco Date: Tue, 4 Jul 2023 00:25:25 +0100 Subject: [PATCH] docs: add contributing guide --- CONTRIBUTING.md | 88 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 47 ++------------------------ 2 files changed, 90 insertions(+), 45 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..9621360 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,88 @@ +# Contributing + +If you want to make changes to the code, you can build from source, and run the API. + +## Build Dependencies + +* cmake + +### Debian / Ubuntu + +```sh +sudo apt-get install cmake +``` + +### Fedora / RHEL + +```sh +sudo dnf install cmake +``` + +## Getting Started + +```bash +git clone https://github.com/LibreTranslate/LibreTranslate.git +cd LibreTranslate +pip install -e . +libretranslate [args] + +# Or +python main.py [args] +``` + +Then open a web browser to + +## Run with Docker + +Linux/macOS: `./run.sh [args]` +Windows: `run.bat [args]` + +Then open a web browser to + +## Build with Docker + +```bash +docker build -f docker/Dockerfile [--build-arg with_models=true] -t libretranslate . +``` + +If you want to run the Docker image in a complete offline environment, you need to add the `--build-arg with_models=true` parameter. Then the language models are downloaded during the build process of the image. Otherwise, these models get downloaded on the first run of the image/container. + +Run the built image: + +```bash +docker run -it -p 5000:5000 libretranslate [args] +``` + +Or build and run using Docker Compose: + +```bash +docker compose up -d --build +``` + +> Feel free to change the [`docker-compose.yml`](https://github.com/LibreTranslate/LibreTranslate/blob/main/docker-compose.yml) file to adapt it to your deployment needs, or use an extra `docker-compose.prod.yml` file for your deployment configuration. +> +> The models are stored inside the container under `/home/libretranslate/.local/share` and `/home/libretranslate/.local/cache`. Feel free to use volumes if you do not want to redownload the models when the container is destroyed. To update the models, use the `--update-models` argument. + +## FAQ + +### Externally Managed Environment + +Some users may encounter the following error while installing packages: + +``` +error: externally-managed-environment + +× This environment is externally managed +╰─> To install Python packages system-wide, try apt install + python3-xyz, where xyz is the package you are trying to + install. + + … +``` + +This occurs when your operating system depends on and manages Python for core functionality. In this case, you should install and setup venv (virtual environments) to manage project dependencies. + +This prevents pip packages from being installed system-wide. This way, there are no risks of pip packages conflicting between multiple projects or the operating system. + +References: +* [Python venv documentation](https://docs.python.org/library/venv.html) diff --git a/README.md b/README.md index e755aca..6fb2031 100644 --- a/README.md +++ b/README.md @@ -112,50 +112,7 @@ On Ubuntu 20.04 you can also use the install script available at - -### Run with Docker - -Linux/MacOS: `./run.sh [args]` -Windows: `run.bat [args]` - -Then open a web browser to - -### Build with Docker - -```bash -docker build -f docker/Dockerfile [--build-arg with_models=true] -t libretranslate . -``` - -If you want to run the Docker image in a complete offline environment, you need to add the `--build-arg with_models=true` parameter. Then the language models are downloaded during the build process of the image. Otherwise these models get downloaded on the first run of the image/container. - -Run the built image: - -```bash -docker run -it -p 5000:5000 libretranslate [args] -``` - -Or build and run using `docker-compose`: - -```bash -docker-compose up -d --build -``` - -> Feel free to change the [`docker-compose.yml`](https://github.com/LibreTranslate/LibreTranslate/blob/main/docker-compose.yml) file to adapt it to your deployment needs, or use an extra `docker-compose.prod.yml` file for your deployment configuration. -> -> The models are stored inside the container under `/home/libretranslate/.local/share` and `/home/libretranslate/.local/cache`. Feel free to use volumes if you do not want to redownload the models when the container is destroyed. To update the models, use the `--update-models` argument. +See [CONTIRBUTING.md](./CONTRIBUTING.md) for information on how to build and run the project yourself. ### CUDA @@ -164,7 +121,7 @@ You can use hardware acceleration to speed up translations on a GPU machine with Run this version with: ```bash -docker-compose -f docker-compose.cuda.yml up -d --build +docker compose -f docker-compose.cuda.yml up -d --build ``` ## Arguments