Skip to content

Commit 40dcf3a

Browse files
PaulaYanizPaulaYaniz
committed
docs: move developer setup guides to separate files
Per review feedback on #885, moved Linux and macOS developer setup instructions into dedicated LINUX_SETUP.md and MACOS_SETUP.md files. README now links to both. These will be referenced from the upcoming CONTRIBUTING.md (#860).
1 parent e1c891f commit 40dcf3a

3 files changed

Lines changed: 148 additions & 145 deletions

File tree

‎LINUX_SETUP.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Developer setup (Linux)
2+
3+
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.
4+
5+
## 1. Fork and clone this repo
6+
```bash
7+
git clone git@github.com:[username]/malariagen-data-python.git
8+
cd malariagen-data-python
9+
```
10+
11+
## 2. Install Python
12+
```bash
13+
sudo add-apt-repository ppa:deadsnakes/ppa
14+
sudo apt install python3.10 python3.10-venv
15+
```
16+
17+
## 3. Install pipx and poetry
18+
```bash
19+
python3.10 -m pip install --user pipx
20+
python3.10 -m pipx ensurepath
21+
pipx install poetry
22+
```
23+
24+
## 4. Create and activate development environment
25+
```bash
26+
poetry install
27+
poetry shell
28+
```
29+
30+
## 5. Install pre-commit hooks
31+
```bash
32+
pipx install pre-commit
33+
pre-commit install
34+
```
35+
36+
Run pre-commit checks manually:
37+
```bash
38+
pre-commit run --all-files
39+
```
40+
41+
## 6. Run tests
42+
43+
Run fast unit tests using simulated data:
44+
```bash
45+
poetry run pytest -v tests/anoph
46+
```
47+
48+
## 7. Google Cloud authentication (for legacy tests)
49+
50+
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).
51+
52+
Once access has been granted, [install the Google Cloud CLI](https://cloud.google.com/sdk/docs/install):
53+
```bash
54+
./install_gcloud.sh
55+
```
56+
57+
Then obtain application-default credentials:
58+
```bash
59+
./google-cloud-sdk/bin/gcloud auth application-default login
60+
```
61+
62+
Once authenticated, run legacy tests:
63+
```bash
64+
poetry run pytest --ignore=tests/anoph -v tests
65+
```
66+
67+
Tests will run slowly the first time, as data will be read from GCS and cached locally in the `gcs_cache` folder.

‎MACOS_SETUP.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Developer setup (macOS)
2+
3+
The Linux setup guide is available in [LINUX_SETUP.md](LINUX_SETUP.md). If you are on macOS, follow these steps instead.
4+
5+
## 1. Install Miniconda
6+
7+
Download and install Miniconda for macOS from https://docs.conda.io/en/latest/miniconda.html.
8+
Choose the Apple Silicon installer if you have an Apple Silicon Mac, or the Intel installer otherwise. You can check with:
9+
```bash
10+
uname -m
11+
# arm64 = Apple Silicon, x86_64 = Intel
12+
```
13+
14+
After installation, close and reopen your terminal for conda to be available.
15+
16+
## 2. Create a conda environment
17+
18+
The package requires Python `>=3.10, <3.13`. Python 3.13+ is not currently supported.
19+
```bash
20+
conda create -n malariagen python=3.11
21+
conda activate malariagen
22+
```
23+
24+
## 3. Fork and clone this repo
25+
26+
Fork the repository on GitHub, then clone your fork:
27+
```bash
28+
git clone git@github.com:[username]/malariagen-data-python.git
29+
cd malariagen-data-python
30+
pip install -e ".[dev]"
31+
```
32+
33+
## 4. Install pre-commit hooks
34+
```bash
35+
pre-commit install
36+
```
37+
38+
Run pre-commit checks manually:
39+
```bash
40+
pre-commit run --all-files
41+
```
42+
43+
## 5. Run tests
44+
45+
Run fast unit tests using simulated data:
46+
```bash
47+
pytest -v tests/anoph
48+
```
49+
50+
## 6. Google Cloud authentication (for legacy tests)
51+
52+
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).
53+
54+
Once access has been granted, install the Google Cloud CLI:
55+
```bash
56+
brew install google-cloud-sdk
57+
```
58+
59+
Then authenticate:
60+
```bash
61+
gcloud auth application-default login
62+
```
63+
64+
This opens a browser — log in with any Google account.
65+
66+
Once authenticated, run legacy tests:
67+
```bash
68+
pytest --ignore=tests/anoph -v tests
69+
```
70+
71+
Tests will run slowly the first time, as data will be read from GCS and cached locally in the `gcs_cache` folder.
72+
73+
## 7. VS Code terminal integration
74+
75+
To use the `code` command from the terminal:
76+
77+
Open VS Code → `Cmd + Shift + P` → type `Shell Command: Install 'code' command in PATH` → press Enter.

‎README.md‎

Lines changed: 4 additions & 145 deletions
Original file line numberDiff line numberDiff line change
@@ -44,152 +44,11 @@ for release notes.
4444

4545
## Developer setup
4646

47-
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.
47+
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).
4848

49-
> **macOS users:** See the [macOS setup section](#developer-setup-macos) below.
50-
51-
Fork and clone this repo:
52-
53-
```bash
54-
git clone git@github.com:[username]/malariagen-data-python.git
55-
```
56-
57-
Install Python, e.g.:
58-
59-
```bash
60-
sudo add-apt-repository ppa:deadsnakes/ppa
61-
sudo apt install python3.10 python3.10-venv
62-
```
63-
64-
Install pipx, e.g.:
65-
66-
```bash
67-
python3.10 -m pip install --user pipx
68-
python3.10 -m pipx ensurepath
69-
```
70-
71-
Install [poetry](https://python-poetry.org/docs/#installation), e.g.:
72-
73-
```bash
74-
pipx install poetry
75-
```
76-
77-
Create development environment:
78-
79-
```bash
80-
cd malariagen-data-python
81-
poetry use 3.10
82-
poetry install
83-
```
84-
85-
Activate development environment:
86-
87-
```bash
88-
poetry shell
89-
```
90-
91-
Install pre-commit and pre-commit hooks:
92-
93-
```bash
94-
pipx install pre-commit
95-
pre-commit install
96-
```
97-
98-
Run pre-commit checks (isort, black, blackdoc, flake8, ...) manually:
99-
100-
```bash
101-
pre-commit run --all-files
102-
```
103-
104-
Run fast unit tests using simulated data:
105-
106-
```bash
107-
poetry run pytest -v tests/anoph
108-
```
109-
110-
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).
111-
112-
Once access has been granted, [install the Google Cloud CLI](https://cloud.google.com/sdk/docs/install). E.g., if on Linux:
113-
114-
```bash
115-
./install_gcloud.sh
116-
```
117-
118-
You'll then need to obtain application-default credentials, e.g.:
119-
120-
```bash
121-
./google-cloud-sdk/bin/gcloud auth application-default login
122-
```
123-
124-
Once this is done, you can run legacy tests:
125-
126-
```bash
127-
poetry run pytest --ignore=tests/anoph -v tests
128-
```
129-
130-
Tests will run slowly the first time, as data required for testing
131-
will be read from GCS. Subsequent runs will be faster as data will be
132-
cached locally in the "gcs_cache" folder.
133-
134-
## Developer setup (macOS)
135-
136-
The instructions above are Linux-focused. If you are on macOS, follow these steps instead.
137-
138-
### Install Miniconda
139-
140-
Download and install Miniconda for macOS from https://docs.conda.io/en/latest/miniconda.html.
141-
Choose the Apple Silicon installer if you have an M1/M2/M3 chip, or the Intel installer otherwise. You can check with:
142-
```bash
143-
uname -m
144-
# arm64 = Apple Silicon, x86_64 = Intel
145-
```
146-
147-
After installation, close and reopen your terminal for conda to be available.
148-
149-
### Create a conda environment
150-
151-
The package requires Python >=3.10 and <3.13. Python 3.13+ is not currently supported.
152-
```bash
153-
conda create -n malariagen python=3.11
154-
conda activate malariagen
155-
```
156-
157-
### Fork, clone and install
158-
```bash
159-
git clone https://github.com/[username]/malariagen-data-python.git
160-
cd malariagen-data-python
161-
pip install -e ".[dev]"
162-
```
163-
164-
### Install pre-commit hooks
165-
```bash
166-
pre-commit install
167-
```
168-
169-
### Run fast unit tests
170-
```bash
171-
pytest -v tests/anoph
172-
```
173-
174-
### Google Cloud authentication
175-
176-
To run legacy tests or access data from GCS, install the Google Cloud CLI:
177-
```bash
178-
brew install google-cloud-sdk
179-
```
180-
181-
Then authenticate:
182-
```bash
183-
gcloud auth application-default login
184-
```
185-
186-
This opens a browser — log in with any Google account. You will also need to [request access to MalariaGEN data on GCS](https://malariagen.github.io/vector-data/vobs/vobs-data-access.html).
187-
188-
### VS Code terminal integration
189-
190-
To use the `code` command from the terminal:
191-
192-
Open VS Code → `Cmd + Shift + P` → type `Shell Command: Install 'code' command in PATH` → press Enter.
49+
For detailed setup instructions, see:
50+
- [Linux setup guide](LINUX_SETUP.md)
51+
- [macOS setup guide](MACOS_SETUP.md)
19352

19453
## Release process
19554

0 commit comments

Comments
 (0)