From 83a62900659d86eb16678b3f90c866756780f551 Mon Sep 17 00:00:00 2001 From: pabera <1260686+pabera@users.noreply.github.com> Date: Sun, 10 Dec 2023 21:33:52 +0100 Subject: [PATCH] [Docs] Inform about Python venv --- documentation/developers/README.md | 2 +- .../developers/development-environment.md | 59 +++++++------------ documentation/developers/pyhton.md | 18 ++++++ 3 files changed, 41 insertions(+), 38 deletions(-) create mode 100644 documentation/developers/pyhton.md diff --git a/documentation/developers/README.md b/documentation/developers/README.md index 9136c5f31..6c973d6ba 100644 --- a/documentation/developers/README.md +++ b/documentation/developers/README.md @@ -3,7 +3,7 @@ ## Getting started * [Development Environment](./development-environment.md) -* [Setting up Docker](./docker.md) +* [Python Development Notes](pyhton.md) ## Reference diff --git a/documentation/developers/development-environment.md b/documentation/developers/development-environment.md index d79a6101e..9abefbee0 100644 --- a/documentation/developers/development-environment.md +++ b/documentation/developers/development-environment.md @@ -1,30 +1,30 @@ # Development Environment -You have 3 development options: -## Directly on Raspberry Pi -The full setup is running on the RPi and you access files via SSH. -Pretty easy to set up as you simply do a normal install and switch to -the `future3/develop` branch. +You have 3 development options. Each option has its pros and cons. To interact with GPIO or other hardware, it's required to develop directly on a Raspberry Pi. For general development of Python code (Jukebox) or JavaScript (Webapp), we recommend Docker. Developing on your local machine (Linux, Mac, Windows) works as well and requires all dependencies to be installed locally. + +* [Develop in Docker](#develop-in-docker) +* [Develop on Raspberry Pi](#develop-on-raspberry-pi) +* [Develop on local machine](#develop-on-local-machine) + +## Develop in Docker + +There is a complete [Docker setup](./docker.md). + +## Develop on Raspberry Pi + +The full setup is running on the RPi and you access files via SSH. Pretty easy to set up as you simply do a normal install and switch to the `future3/develop` branch. ### Steps to install -We recommend to use at least a Pi 3 or Pi Zero 2 for development. This -hardware won\'t be needed in production, but it can be slow while -developing. +We recommend to use at least a Pi 3 or Pi Zero 2 for development. This hardware won\'t be needed in production, but it can be slow while developing. 1. Install the latest Pi OS on a SD card. 2. Boot up your Raspberry Pi. -3. [Install](../builders/installation.md) the Jukebox software as if you were building a - Phoniebox. You can install from your own fork and feature branch if - you wish which can be changed later as well. The original repository - will be set as `upstream`. +3. [Install](../builders/installation.md) the Jukebox software as if you were building a Phoniebox. You can install from your own fork and feature branch you wish which can be changed later as well. The original repository will be set as `upstream`. 4. Once the installation has successfully ran, reboot your Pi. -5. Due to some resource constraints, the Webapp does not build the - latest changes and instead consumes the latest official release. To - change that, you need to install NodeJS and build the Webapp - locally. +5. Due to some resource constraints, the Webapp does not build the latest changes and instead consumes the latest official release. To change that, you need to install NodeJS and build the Webapp locally. 6. Install NodeJS using the existing installer ``` bash @@ -34,8 +34,7 @@ developing. ``` 7. To free up RAM, reboot your Pi. -8. Build the Webapp using the existing build command. If the build - fails, you might have forgotten to reboot. +8. Build the Webapp using the existing build command. If the build fails, you might have forgotten to reboot. ``` bash cd ~/RPi-Jukebox-RFID/src/webapp; \ @@ -43,30 +42,16 @@ developing. ``` 9. The Webapp should now be updated. -10. To continuously update Webapp, pull the latest changes from your - repository and rerun the command above. +10. To continuously update Webapp, pull the latest changes from your repository and rerun the command above. -## Locally on any Linux machine +## Develop on local machine -The jukebox also runs on any Linux machine. The Raspberry Pi specific -stuff will not work of course. That is no issue depending our your -development area. USB RFID Readers, however, will work. You will have -to install and configure [MPD (Music Player -Daemon)](https://www.musicpd.org/). +The jukebox also runs on any Linux machine. The Raspberry Pi specific stuff will not work of course. That is no issue depending our your development area. USB RFID Readers, however, will work. You will have to install and configure [MPD (Music Player Daemon)](https://www.musicpd.org/). -In addition to the `requirements.txt`, you will this -dependency. On the Raspberry PI, the latest stable release of ZMQ does -not support WebSockets. We need to compile the latest version from -Github, which is taken care of by the installation script. For regular -machines, the normal package can be installed: +In addition to the `requirements.txt`, you will this dependency. On the Raspberry PI, the latest stable release of ZMQ does not support WebSockets. We need to compile the latest version from Github, which is taken care of by the installation script. For regular machines, the normal package can be installed: ``` bash pip install pyzmq ``` -You will have to start Jukebox core application and the WebUI -separately. The MPD usually runs as a service. - -## Using Docker container - -There is a complete [Docker setup](./docker.md). +You will have to start Jukebox core application and the WebUI separately. The MPD usually runs as a service. diff --git a/documentation/developers/pyhton.md b/documentation/developers/pyhton.md new file mode 100644 index 000000000..e9a071e34 --- /dev/null +++ b/documentation/developers/pyhton.md @@ -0,0 +1,18 @@ +# Python Development Notes + +## Prerequisites + +> [!NOTE] +> All Python scripts must be run within a [virtual environment](https://docs.python.org/3/library/venv.html) (`.venv`). All Python plugins are installed encapsulated within this environment. + +Before you can run Python code, you need to enable the virtual environment. On the Raspberry Pi, it's located in the project root `~/RPi-Jukebox-RFID/.venv`. Depending on your setup, the absolute path can vary. + +``` +$ ~/RPi-Jukebox-RFID/.venv/bin/activate +``` + +If the virtual environment has been activated correctly, your terminal will now show a prefix (`.venv`). If you want to leave the venv again execute deactivate. + +``` +$ ~/RPi-Jukebox-RFID/.venv/bin/deactivate +```