Merge pull request #1099 from Schronding/GH1091-debian-setup-docs

Add DEBIAN_SETUP.md to support Debian and WSL environments (Fixes #1091)

Author: jonbrenas

LINUX_SETUP.md

@@ -1,65 +1,138 @@
 # Developer setup (Linux)
 
-To get setup for development, see [this video if you prefer VS Code](https://youtu.be/zddl3n1DCFM), or [this older video if you prefer PyCharm](https://youtu.be/QniQi-Hoo9A), and the instructions below.
+## 1. Install Git
+
+Choose the command for your Linux distribution:
+
+**Ubuntu, Debian, and Mint:**
+
+```bash
+sudo apt update
+sudo apt install -y git
+```
+
+**Fedora:**
 
-## 1. Fork and clone this repo
 ```bash
-git clone git@github.com:[username]/malariagen-data-python.git
+sudo dnf install -y git
+```
+
+**Arch Linux:**
+
+```bash
+sudo pacman -S sudo
+sudo pacman -S git
+sudo pacman -S openssh
+```
+
+If your Arch install does not have `sudo` configured yet, run the commands above as `root`, then configure `sudo` for your user.
+
+## 2. Fork and clone this repo
+
+After forking the repository on GitHub, clone your fork.
+
+Use SSH if your SSH keys are set up:
+
+```bash
+git clone git@github.com:[YOUR_GITHUB_USERNAME]/malariagen-data-python.git
 cd malariagen-data-python
 ```
 
-## 2. Install Python
+Use HTTPS if you prefer, or if you do not have SSH keys configured (common on WSL):
+
+```bash
+git clone https://github.com/[YOUR_GITHUB_USERNAME]/malariagen-data-python.git
+cd malariagen-data-python
+```
+
+## 3. Install pipx
+
+Choose the command for your Linux distribution:
+
+**Ubuntu, Debian, and Mint:**
+
+```bash
+sudo apt update
+sudo apt install -y pipx
+pipx ensurepath
+```
+
+**Fedora:**
+
+```bash
+sudo dnf install -y pipx
+pipx ensurepath
+```
+
+**Arch Linux:**
+
 ```bash
-sudo add-apt-repository ppa:deadsnakes/ppa
-sudo apt install python3.10 python3.10-venv
+sudo pacman -S python-pipx
+pipx ensurepath
 ```
 
-## 3. Install pipx and poetry
+Close and reopen your terminal to apply PATH changes.
+If you prefer to reload the shell in-place, run:
+
+```bash
+exec bash
+```
+
+## 4. Install Poetry and Python 3.12
+
+The package requires `>=3.10,<3.13`. We use Poetry's built-in installer to handle the Python version universally across all distributions.
+
 ```bash
-python3.10 -m pip install --user pipx
-python3.10 -m pipx ensurepath
 pipx install poetry
+poetry python install 3.12
 ```
 
-## 4. Create and activate development environment
+## 5. Create development environment
+
 ```bash
-poetry install
-poetry shell
+poetry env use 3.12
+poetry install --extras dev
 ```
 
-## 5. Install pre-commit hooks
+## 6. Install pre-commit hooks
+
 ```bash
 pipx install pre-commit
 pre-commit install
 ```
 
 Run pre-commit checks manually:
+
 ```bash
 pre-commit run --all-files
 ```
 
-## 6. Run tests
+## 7. Run tests
 
 Run fast unit tests using simulated data:
+
 ```bash
 poetry run pytest -v tests/anoph
 ```
 
-## 7. Google Cloud authentication (for legacy tests)
+## 8. Google Cloud authentication (for legacy tests)
 
 To run legacy tests which read data from GCS, you'll need to [request access to MalariaGEN data on GCS](https://malariagen.github.io/vector-data/vobs/vobs-data-access.html).
 
 Once access has been granted, [install the Google Cloud CLI](https://cloud.google.com/sdk/docs/install):
+
 ```bash
 ./install_gcloud.sh
 ```
 
 Then obtain application-default credentials:
+
 ```bash
 ./google-cloud-sdk/bin/gcloud auth application-default login
 ```
 
 Once authenticated, run legacy tests:
+
 ```bash
 poetry run pytest --ignore=tests/anoph -v tests
 ```