From 679017db7ca7a1703d8577d497634e8b94cb44ce Mon Sep 17 00:00:00 2001
From: Rodrigo V Honorato <r.vargashonorato@uu.nl>
Date: Fri, 30 Aug 2024 11:11:18 +0200
Subject: [PATCH 01/24] add `DEVELOPMENT.md`

---
 DEVELOPMENT.md | 138 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 138 insertions(+)
 create mode 100644 DEVELOPMENT.md

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
new file mode 100644
index 000000000..f52c2e033
--- /dev/null
+++ b/DEVELOPMENT.md
@@ -0,0 +1,138 @@
+# Developing HADDOCK3
+
+This file provides information on how to setup a development environment for HADDOCK3.
+
+- [System requirements](#system-requirements)
+  - [Python3.9](#python39)
+  - [CNS](#cns)
+  - [git](#git)
+  - [gcc](#gcc)
+  - [OpenMPI](#openmpi)
+- [Setting up the development environment](#setting-up-the-development-environment)
+  - [Clone the repository](#clone-the-repository)
+  - [Link CNS binary](#link-cns-binary)
+  - [Install shipped C++ dependencies](#install-shipped-c-dependencies)
+    - [fcc](#fcc)
+    - [fast-rmsdmatrix](#fast-rmsdmatrix)
+  - [Python environment](#python-environment)
+  - [Install Python dependencies](#install-python-dependencies)
+  - [Running tests](#running-tests)
+
+## System requirements
+
+- Python 3.9
+- CNS
+- git
+- gcc
+- OpenMPI
+
+### Installing system dependencies
+
+Below the instructions are provided for a Ubuntu system using `apt-get`. If you are using a different system, please refer to the respective package manager - `yum`, `dnf`, `pacman`, `homebrew`, `port`, etc.
+
+#### Python3.9
+
+Conda is NOT recomended for development. Instead, install and compile Python 3.9 from source.
+
+```bash
+wget https://www.python.org/ftp/python/3.9.6/Python-3.9.6.tgz
+tar -xf Python-3.9.6.tgz
+cd Python-3.9.6
+./configure --enable-optimizations
+sudo make altinstall -j 8
+```
+
+Then `python3.9` should be available on your system, at `/usr/local/bin/python3.9`
+
+#### CNS
+
+Please refer to the [CNS installation instructions](docs/CNS.md).
+
+#### Git
+
+```bash
+sudo apt-get install git
+```
+
+#### gcc
+
+```bash
+sudo apt-get install gcc
+```
+
+#### OpenMPI
+
+```bash
+sudo apt-get install openmpi-bin libopenmpi3 libopenmpi-dev
+```
+
+## Setting up the development environment
+
+### Clone the repository
+
+```bash
+git clone --recursive git://github.com/haddocking/haddock3.git
+```
+
+### Link CNS binary
+
+```bash
+mkdir haddock3/bin
+ln -s /path/to/cns_solve_1.3/bin/cns haddock3/bin/cns
+```
+
+### Install shipped C++ dependencies
+
+#### fcc
+
+```bash
+cd src/fcc/src
+make
+```
+
+#### fast-rmsdmatrix
+
+```bash
+cd src/fast-rmsdmatrix/src
+make fast-rmsdmatrix
+```
+
+### Python environment
+
+We recomend you use Python's native virtual environment to manage the dependencies.
+
+```bash
+/usr/local/bin/python3.9 -m venv .venv
+source .venv/bin/activate
+```
+
+### Install Python dependencies
+
+Install both project dependencies and test dependencies using pip.
+
+```bash
+pip install -r requirements.txt &&
+  pip install \
+    coverage==7.2.5 \
+    pytest==7.3.1 \
+    pytest-cov==4.0.0 \
+    hypothesis==6.75.1 \
+    pytest-mock==3.12.0 \
+    fastapi==0.110.1 \
+    httpx==0.27.0 \
+    mpi4py==3.1.6
+```
+
+Install haddock3 in development mode.
+
+```bash
+python setup.py develop
+```
+
+## Running tests
+
+Simply run the following command to run the tests.
+
+```bash
+pytest
+```

From 2e49f69248ad7a8abf5efd818aeee070743a1989 Mon Sep 17 00:00:00 2001
From: Alexandre Bonvin <alexandre.bonvin@gmail.com>
Date: Fri, 30 Aug 2024 17:03:09 +0200
Subject: [PATCH 02/24] Update DEVELOPMENT.md

correct git clone command to use https address
---
 DEVELOPMENT.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index f52c2e033..5a951dd6b 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -71,7 +71,7 @@ sudo apt-get install openmpi-bin libopenmpi3 libopenmpi-dev
 ### Clone the repository
 
 ```bash
-git clone --recursive git://github.com/haddocking/haddock3.git
+git clone --recursive https://github.com/haddocking/haddock3.git
 ```
 
 ### Link CNS binary

From 3d289832c0cdeccb52757fee1d34d3741ac5a3de Mon Sep 17 00:00:00 2001
From: Alexandre Bonvin <alexandre.bonvin@gmail.com>
Date: Fri, 30 Aug 2024 17:25:43 +0200
Subject: [PATCH 03/24] Update DEVELOPMENT.md

Updating instructions
---
 DEVELOPMENT.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index 5a951dd6b..1b28b17f7 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -88,6 +88,7 @@ ln -s /path/to/cns_solve_1.3/bin/cns haddock3/bin/cns
 ```bash
 cd src/fcc/src
 make
+cd ../../
 ```
 
 #### fast-rmsdmatrix
@@ -95,6 +96,7 @@ make
 ```bash
 cd src/fast-rmsdmatrix/src
 make fast-rmsdmatrix
+cd ../../
 ```
 
 ### Python environment

From 02fcdbe40f4d2ed6ef8068b873311c4c875a8e83 Mon Sep 17 00:00:00 2001
From: Alexandre Bonvin <alexandre.bonvin@gmail.com>
Date: Fri, 30 Aug 2024 17:26:48 +0200
Subject: [PATCH 04/24] Update DEVELOPMENT.md

---
 DEVELOPMENT.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index 1b28b17f7..da10aa854 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -88,7 +88,7 @@ ln -s /path/to/cns_solve_1.3/bin/cns haddock3/bin/cns
 ```bash
 cd src/fcc/src
 make
-cd ../../
+cd ../../../
 ```
 
 #### fast-rmsdmatrix

From 1ccd6b1a9a3432853d2a882f127cceaa18a5e682 Mon Sep 17 00:00:00 2001
From: Alexandre Bonvin <alexandre.bonvin@gmail.com>
Date: Fri, 30 Aug 2024 17:41:43 +0200
Subject: [PATCH 05/24] Update DEVELOPMENT.md

Added OSX instructions
---
 DEVELOPMENT.md | 28 ++++++++++++++++++++++++----
 1 file changed, 24 insertions(+), 4 deletions(-)

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index da10aa854..add1e95dc 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -32,8 +32,9 @@ Below the instructions are provided for a Ubuntu system using `apt-get`. If you
 
 #### Python3.9
 
-Conda is NOT recomended for development. Instead, install and compile Python 3.9 from source.
+Conda is NOT recommended for development. Instead, install and compile Python 3.9 from source.
 
+On a __Linux-based system__ you can install Python 3.9 with the following commands:
 ```bash
 wget https://www.python.org/ftp/python/3.9.6/Python-3.9.6.tgz
 tar -xf Python-3.9.6.tgz
@@ -42,7 +43,16 @@ cd Python-3.9.6
 sudo make altinstall -j 8
 ```
 
-Then `python3.9` should be available on your system, at `/usr/local/bin/python3.9`
+Then `python3.9` should be available on your system at `/usr/local/bin/python3.9`
+
+On __OSX__, use rather [brew](https://brew.sh) to install Python 3.9:
+
+```bash
+brew install python@3.9
+```
+
+Then `python3.9 should be available on your system at `/opt/homebrew/bin/python3.9`
+
 
 #### CNS
 
@@ -60,11 +70,13 @@ sudo apt-get install git
 sudo apt-get install gcc
 ```
 
-#### OpenMPI
+#### OpenMPI 
 
 ```bash
 sudo apt-get install openmpi-bin libopenmpi3 libopenmpi-dev
 ```
+__Note__ that this step is not required on OSX.
+
 
 ## Setting up the development environment
 
@@ -96,7 +108,7 @@ cd ../../../
 ```bash
 cd src/fast-rmsdmatrix/src
 make fast-rmsdmatrix
-cd ../../
+cd ../../../
 ```
 
 ### Python environment
@@ -108,6 +120,14 @@ We recomend you use Python's native virtual environment to manage the dependenci
 source .venv/bin/activate
 ```
 
+On __OSX__ the command would be:
+
+```bash
+/opt/homebrew/bin/python3.9 -m venv .venv
+source .venv/bin/activate
+```
+
+
 ### Install Python dependencies
 
 Install both project dependencies and test dependencies using pip.

From 13ef1c4809957daa4518cad6dc6a3309c2d9514b Mon Sep 17 00:00:00 2001
From: Alexandre Bonvin <alexandre.bonvin@gmail.com>
Date: Fri, 30 Aug 2024 17:42:14 +0200
Subject: [PATCH 06/24] Update DEVELOPMENT.md

---
 DEVELOPMENT.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index add1e95dc..05db82f58 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -51,7 +51,7 @@ On __OSX__, use rather [brew](https://brew.sh) to install Python 3.9:
 brew install python@3.9
 ```
 
-Then `python3.9 should be available on your system at `/opt/homebrew/bin/python3.9`
+Then `python3.9` should be available on your system at `/opt/homebrew/bin/python3.9`
 
 
 #### CNS

From 3209c6c0967a426d99e1953da9d66566b5e1856e Mon Sep 17 00:00:00 2001
From: Alexandre Bonvin <alexandre.bonvin@gmail.com>
Date: Fri, 30 Aug 2024 17:43:38 +0200
Subject: [PATCH 07/24] Update DEVELOPMENT.md

---
 DEVELOPMENT.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index 05db82f58..a9b0b165e 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -60,18 +60,24 @@ Please refer to the [CNS installation instructions](docs/CNS.md).
 
 #### Git
 
+On a __Linux-based__ system:
+
 ```bash
 sudo apt-get install git
 ```
 
 #### gcc
 
+On a __Linux-based__ system:
+
 ```bash
 sudo apt-get install gcc
 ```
 
 #### OpenMPI 
 
+On a __Linux-based__ system:
+
 ```bash
 sudo apt-get install openmpi-bin libopenmpi3 libopenmpi-dev
 ```

From af86ae10de8094aa85d99beae7e042d6879d6b32 Mon Sep 17 00:00:00 2001
From: Alexandre Bonvin <alexandre.bonvin@gmail.com>
Date: Sun, 22 Sep 2024 18:23:56 +0200
Subject: [PATCH 08/24] Update DEVELOPMENT.md

Added a short section about HPC environment
---
 DEVELOPMENT.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index a9b0b165e..a379015bf 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -157,6 +157,12 @@ Install haddock3 in development mode.
 python setup.py develop
 ```
 
+## Installation in an HPC environment
+
+For installation in an HPC environment we recommend to check the installed Python versions on the system and also importantly if an openmpi (or other custom MPI) installation is available on the system. Those are often offered via the `module` command.
+If you only intend to test haddock3 in local mode, the above instructions should be fine. But to harvest the MPI capabilities of an HPC system it is best to build haddock3 using the installed MPI version on the HPC system.
+
+
 ## Running tests
 
 Simply run the following command to run the tests.

From c3d55ae0dcc1c93d336b5144a742c3721ce26402 Mon Sep 17 00:00:00 2001
From: Rodrigo V Honorato <r.vargashonorato@uu.nl>
Date: Mon, 23 Sep 2024 12:14:38 +0200
Subject: [PATCH 09/24] tweaks

---
 DEVELOPMENT.md | 63 ++++++++++++--------------------------------------
 1 file changed, 15 insertions(+), 48 deletions(-)

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index a379015bf..cfa2e8439 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -4,16 +4,11 @@ This file provides information on how to setup a development environment for HAD
 
 - [System requirements](#system-requirements)
   - [Python3.9](#python39)
-  - [CNS](#cns)
   - [git](#git)
   - [gcc](#gcc)
   - [OpenMPI](#openmpi)
 - [Setting up the development environment](#setting-up-the-development-environment)
   - [Clone the repository](#clone-the-repository)
-  - [Link CNS binary](#link-cns-binary)
-  - [Install shipped C++ dependencies](#install-shipped-c-dependencies)
-    - [fcc](#fcc)
-    - [fast-rmsdmatrix](#fast-rmsdmatrix)
   - [Python environment](#python-environment)
   - [Install Python dependencies](#install-python-dependencies)
   - [Running tests](#running-tests)
@@ -32,9 +27,10 @@ Below the instructions are provided for a Ubuntu system using `apt-get`. If you
 
 #### Python3.9
 
-Conda is NOT recommended for development. Instead, install and compile Python 3.9 from source.
+**Conda is NOT recommended for development. Instead, install and compile Python 3.9 from source.**
+
+On a **Linux-based system** you can install Python 3.9 with the following commands:
 
-On a __Linux-based system__ you can install Python 3.9 with the following commands:
 ```bash
 wget https://www.python.org/ftp/python/3.9.6/Python-3.9.6.tgz
 tar -xf Python-3.9.6.tgz
@@ -45,7 +41,7 @@ sudo make altinstall -j 8
 
 Then `python3.9` should be available on your system at `/usr/local/bin/python3.9`
 
-On __OSX__, use rather [brew](https://brew.sh) to install Python 3.9:
+On **OSX**, use rather [brew](https://brew.sh) to install Python 3.9:
 
 ```bash
 brew install python@3.9
@@ -53,14 +49,9 @@ brew install python@3.9
 
 Then `python3.9` should be available on your system at `/opt/homebrew/bin/python3.9`
 
-
-#### CNS
-
-Please refer to the [CNS installation instructions](docs/CNS.md).
-
 #### Git
 
-On a __Linux-based__ system:
+On a **Linux-based** system:
 
 ```bash
 sudo apt-get install git
@@ -68,21 +59,21 @@ sudo apt-get install git
 
 #### gcc
 
-On a __Linux-based__ system:
+On a **Linux-based** system:
 
 ```bash
 sudo apt-get install gcc
 ```
 
-#### OpenMPI 
+#### OpenMPI
 
-On a __Linux-based__ system:
+On a **Linux-based** system:
 
 ```bash
 sudo apt-get install openmpi-bin libopenmpi3 libopenmpi-dev
 ```
-__Note__ that this step is not required on OSX.
 
+**Note** that this step is not required on OSX.
 
 ## Setting up the development environment
 
@@ -92,31 +83,6 @@ __Note__ that this step is not required on OSX.
 git clone --recursive https://github.com/haddocking/haddock3.git
 ```
 
-### Link CNS binary
-
-```bash
-mkdir haddock3/bin
-ln -s /path/to/cns_solve_1.3/bin/cns haddock3/bin/cns
-```
-
-### Install shipped C++ dependencies
-
-#### fcc
-
-```bash
-cd src/fcc/src
-make
-cd ../../../
-```
-
-#### fast-rmsdmatrix
-
-```bash
-cd src/fast-rmsdmatrix/src
-make fast-rmsdmatrix
-cd ../../../
-```
-
 ### Python environment
 
 We recomend you use Python's native virtual environment to manage the dependencies.
@@ -126,14 +92,13 @@ We recomend you use Python's native virtual environment to manage the dependenci
 source .venv/bin/activate
 ```
 
-On __OSX__ the command would be:
+On **OSX** the command would be:
 
 ```bash
 /opt/homebrew/bin/python3.9 -m venv .venv
 source .venv/bin/activate
 ```
 
-
 ### Install Python dependencies
 
 Install both project dependencies and test dependencies using pip.
@@ -159,13 +124,15 @@ python setup.py develop
 
 ## Installation in an HPC environment
 
-For installation in an HPC environment we recommend to check the installed Python versions on the system and also importantly if an openmpi (or other custom MPI) installation is available on the system. Those are often offered via the `module` command.
-If you only intend to test haddock3 in local mode, the above instructions should be fine. But to harvest the MPI capabilities of an HPC system it is best to build haddock3 using the installed MPI version on the HPC system.
+**Please get in contact with the system administrator before doing development in a shared HPC environment.**
 
+For installation in an HPC environment we recommend to check the installed Python versions on the system and also importantly if an `openmpi` (or other custom MPI) installation is available on the system.
+Those are often offered via the `module` command.
+If you only intend to develop haddock3 using the multiprocessing scheduler, the above instructions should be fine. But to harvest the MPI capabilities of an HPC system it is best to build haddock3 using the installed MPI version on the HPC system.
 
 ## Running tests
 
-Simply run the following command to run the tests.
+In `haddock3` we use the pytest framework, the tests are located in `tests/` (unit) and `integration_tests/` directories.
 
 ```bash
 pytest

From 3668525d70a57e17f1b4f5ef2c3eaf3a64a6b21b Mon Sep 17 00:00:00 2001
From: Alexandre Bonvin <alexandre.bonvin@gmail.com>
Date: Tue, 24 Sep 2024 09:46:47 +0200
Subject: [PATCH 10/24] Update DEVELOPMENT.md

Some edits.

But the current instructions are missing the installation of CNS. Following the instructions (no issues on OSX with a fresh installation (even mpi4py) works fine, but the tests fail because the cns executable is not defined.
---
 DEVELOPMENT.md | 14 ++++----------
 1 file changed, 4 insertions(+), 10 deletions(-)

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index cfa2e8439..df9f6e49d 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -29,7 +29,7 @@ Below the instructions are provided for a Ubuntu system using `apt-get`. If you
 
 **Conda is NOT recommended for development. Instead, install and compile Python 3.9 from source.**
 
-On a **Linux-based system** you can install Python 3.9 with the following commands:
+On a **Linux-based system** you can install Python 3.9 if needed with the following commands:
 
 ```bash
 wget https://www.python.org/ftp/python/3.9.6/Python-3.9.6.tgz
@@ -73,7 +73,7 @@ On a **Linux-based** system:
 sudo apt-get install openmpi-bin libopenmpi3 libopenmpi-dev
 ```
 
-**Note** that this step is not required on OSX.
+**Note** that this step is not required on OSX but mpi4py
 
 ## Setting up the development environment
 
@@ -81,6 +81,7 @@ sudo apt-get install openmpi-bin libopenmpi3 libopenmpi-dev
 
 ```bash
 git clone --recursive https://github.com/haddocking/haddock3.git
+cd haddock3
 ```
 
 ### Python environment
@@ -88,14 +89,7 @@ git clone --recursive https://github.com/haddocking/haddock3.git
 We recomend you use Python's native virtual environment to manage the dependencies.
 
 ```bash
-/usr/local/bin/python3.9 -m venv .venv
-source .venv/bin/activate
-```
-
-On **OSX** the command would be:
-
-```bash
-/opt/homebrew/bin/python3.9 -m venv .venv
+python3.9 -m venv .venv
 source .venv/bin/activate
 ```
 

From 2627b13ac47779e74802ea04d7a022a5e1498474 Mon Sep 17 00:00:00 2001
From: Alexandre Bonvin <alexandre.bonvin@gmail.com>
Date: Tue, 24 Sep 2024 09:48:49 +0200
Subject: [PATCH 11/24] Update DEVELOPMENT.md

Added not for brew install mpi4py on OSX
---
 DEVELOPMENT.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index df9f6e49d..368d521e7 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -73,7 +73,7 @@ On a **Linux-based** system:
 sudo apt-get install openmpi-bin libopenmpi3 libopenmpi-dev
 ```
 
-**Note** that this step is not required on OSX but mpi4py
+**Note** that this step is not required on OSX.
 
 ## Setting up the development environment
 
@@ -110,6 +110,9 @@ pip install -r requirements.txt &&
     mpi4py==3.1.6
 ```
 
+**Note**: On OSX, if the installation of mpi4py fails, use instead `brew install mpi4py`
+
+
 Install haddock3 in development mode.
 
 ```bash

From f7b8ea5efba17b2bb198c7551fc0835393f2b517 Mon Sep 17 00:00:00 2001
From: Alexandre Bonvin <alexandre.bonvin@gmail.com>
Date: Tue, 24 Sep 2024 09:55:08 +0200
Subject: [PATCH 12/24] Update DEVELOPMENT.md

Co-authored-by: Victor Reys <132575181+VGPReys@users.noreply.github.com>
---
 DEVELOPMENT.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index 368d521e7..691e7c930 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -110,7 +110,7 @@ pip install -r requirements.txt &&
     mpi4py==3.1.6
 ```
 
-**Note**: On OSX, if the installation of mpi4py fails, use instead `brew install mpi4py`
+**Note**: On OSX, if the installation of mpi4py fails, run first `brew install mpi4py`
 
 
 Install haddock3 in development mode.

From 45309798dce8df255c2fbc7ef0e45126b7adce89 Mon Sep 17 00:00:00 2001
From: Rodrigo V Honorato <r.vargashonorato@uu.nl>
Date: Tue, 24 Sep 2024 16:29:49 +0200
Subject: [PATCH 13/24] add system-dependencies

---
 DEVELOPMENT.md | 76 ++++++++++++++++++--------------------------------
 1 file changed, 27 insertions(+), 49 deletions(-)

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index 691e7c930..1dd3e23bd 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -3,10 +3,6 @@
 This file provides information on how to setup a development environment for HADDOCK3.
 
 - [System requirements](#system-requirements)
-  - [Python3.9](#python39)
-  - [git](#git)
-  - [gcc](#gcc)
-  - [OpenMPI](#openmpi)
 - [Setting up the development environment](#setting-up-the-development-environment)
   - [Clone the repository](#clone-the-repository)
   - [Python environment](#python-environment)
@@ -25,11 +21,23 @@ This file provides information on how to setup a development environment for HAD
 
 Below the instructions are provided for a Ubuntu system using `apt-get`. If you are using a different system, please refer to the respective package manager - `yum`, `dnf`, `pacman`, `homebrew`, `port`, etc.
 
-#### Python3.9
+```bash
+sudo apt-get update &&
+    # Needed for building Python
+    sudo apt-get install build-essential python-setuptools python-pip &&
+    sudo apt-get install libncursesw5-dev libgdbm-dev libc6-dev &&
+    sudo apt-get install zlib1g-dev libsqlite3-dev tk-dev &&
+    sudo apt-get install libssl-dev openssl &&
+    sudo apt-get install libffi-dev &&
+    # Needed for haddock3 installation
+    sudo apt-get install git gcc &&
+    # Needed to run the MPI related tests
+    sudo apt-get install openmpi-bin libopenmpi3 libopenmpi-dev
+```
 
-**Conda is NOT recommended for development. Instead, install and compile Python 3.9 from source.**
+After all the system-dependencies are in place, download and compile python:
 
-On a **Linux-based system** you can install Python 3.9 if needed with the following commands:
+**Conda is NOT recommended for development**
 
 ```bash
 wget https://www.python.org/ftp/python/3.9.6/Python-3.9.6.tgz
@@ -47,46 +55,18 @@ On **OSX**, use rather [brew](https://brew.sh) to install Python 3.9:
 brew install python@3.9
 ```
 
-Then `python3.9` should be available on your system at `/opt/homebrew/bin/python3.9`
-
-#### Git
-
-On a **Linux-based** system:
-
-```bash
-sudo apt-get install git
-```
-
-#### gcc
-
-On a **Linux-based** system:
-
-```bash
-sudo apt-get install gcc
-```
-
-#### OpenMPI
-
-On a **Linux-based** system:
-
-```bash
-sudo apt-get install openmpi-bin libopenmpi3 libopenmpi-dev
-```
-
-**Note** that this step is not required on OSX.
-
 ## Setting up the development environment
 
 ### Clone the repository
 
 ```bash
-git clone --recursive https://github.com/haddocking/haddock3.git
+git clone https://github.com/haddocking/haddock3.git
 cd haddock3
 ```
 
 ### Python environment
 
-We recomend you use Python's native virtual environment to manage the dependencies.
+We recommend you use Python's native virtual environment to manage the dependencies.
 
 ```bash
 python3.9 -m venv .venv
@@ -98,20 +78,18 @@ source .venv/bin/activate
 Install both project dependencies and test dependencies using pip.
 
 ```bash
-pip install -r requirements.txt &&
-  pip install \
-    coverage==7.2.5 \
-    pytest==7.3.1 \
-    pytest-cov==4.0.0 \
-    hypothesis==6.75.1 \
-    pytest-mock==3.12.0 \
-    fastapi==0.110.1 \
-    httpx==0.27.0 \
-    mpi4py==3.1.6
+pip install \
+   coverage==7.2.5 \
+   pytest==7.3.1 \
+   pytest-cov==4.0.0 \
+   hypothesis==6.75.1 \
+   pytest-mock==3.12.0 \
+   fastapi==0.110.1 \
+   httpx==0.27.0 \
+   mpi4py==3.1.6
 ```
 
-**Note**: On OSX, if the installation of mpi4py fails, run first `brew install mpi4py`
-
+> If you are using a Mac, if the installation of mpi4py fails, run first `brew install mpi4py`
 
 Install haddock3 in development mode.
 

From 645b4fa144a67ec5c8f455a874f1093bc1c8890f Mon Sep 17 00:00:00 2001
From: Rodrigo V Honorato <r.vargashonorato@uu.nl>
Date: Tue, 24 Sep 2024 16:34:53 +0200
Subject: [PATCH 14/24] update text

---
 DEVELOPMENT.md | 23 +++++++++++------------
 1 file changed, 11 insertions(+), 12 deletions(-)

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index 1dd3e23bd..72ad96285 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -12,9 +12,6 @@ This file provides information on how to setup a development environment for HAD
 ## System requirements
 
 - Python 3.9
-- CNS
-- git
-- gcc
 - OpenMPI
 
 ### Installing system dependencies
@@ -35,7 +32,7 @@ sudo apt-get update &&
     sudo apt-get install openmpi-bin libopenmpi3 libopenmpi-dev
 ```
 
-After all the system-dependencies are in place, download and compile python:
+After all the system-dependencies are in place, download and compile python.
 
 **Conda is NOT recommended for development**
 
@@ -49,7 +46,9 @@ sudo make altinstall -j 8
 
 Then `python3.9` should be available on your system at `/usr/local/bin/python3.9`
 
-On **OSX**, use rather [brew](https://brew.sh) to install Python 3.9:
+On **OSX**, you can use a package-manager such as [brew](https://brew.sh) to install Python 3.9.
+
+> Please keep in mind installing python with a package manager can mask system dependencies that your development might add. That's why we recommended you install it from source.
 
 ```bash
 brew install python@3.9
@@ -73,7 +72,13 @@ python3.9 -m venv .venv
 source .venv/bin/activate
 ```
 
-### Install Python dependencies
+### Install haddock3 in development mode.
+
+```bash
+python setup.py develop
+```
+
+### Install test dependencies
 
 Install both project dependencies and test dependencies using pip.
 
@@ -91,12 +96,6 @@ pip install \
 
 > If you are using a Mac, if the installation of mpi4py fails, run first `brew install mpi4py`
 
-Install haddock3 in development mode.
-
-```bash
-python setup.py develop
-```
-
 ## Installation in an HPC environment
 
 **Please get in contact with the system administrator before doing development in a shared HPC environment.**

From 0d779b4d4189af3fd021740cdef84af92f45b919 Mon Sep 17 00:00:00 2001
From: Rodrigo V Honorato <r.vargashonorato@uu.nl>
Date: Tue, 24 Sep 2024 16:42:16 +0200
Subject: [PATCH 15/24] update ci.yml

---
 .github/workflows/ci.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c92e672f5..f7ac7a8bc 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
           fastapi==0.110.1 httpx==0.27.0 mpi4py==3.1.6
 
       - name: install haddock3
-        run: pip install -v .
+        run: python setup.py -v develop
 
       ## Disabled for now until we figure out a good configuration ##
       # - name: check types

From 83aeb325a28eda62aa28f8f9f087022a4ae7385b Mon Sep 17 00:00:00 2001
From: Rodrigo V Honorato <r.vargashonorato@uu.nl>
Date: Tue, 24 Sep 2024 16:42:39 +0200
Subject: [PATCH 16/24] use specific python3.9 path

---
 DEVELOPMENT.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index 72ad96285..e6181b6b4 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -68,7 +68,7 @@ cd haddock3
 We recommend you use Python's native virtual environment to manage the dependencies.
 
 ```bash
-python3.9 -m venv .venv
+/usr/local/bin/python3.9 -m venv .venv
 source .venv/bin/activate
 ```
 

From e5c8ccae6cc07ad24f920f81e5540a78353ff016 Mon Sep 17 00:00:00 2001
From: Rodrigo V Honorato <r.vargashonorato@uu.nl>
Date: Tue, 24 Sep 2024 16:57:08 +0200
Subject: [PATCH 17/24] add CustomDevelop wrapper

---
 setup.py | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/setup.py b/setup.py
index c1bbe77d5..7e6b522f3 100644
--- a/setup.py
+++ b/setup.py
@@ -11,6 +11,7 @@
 
 from setuptools import Extension, find_packages, setup
 from setuptools.command.build_ext import build_ext
+from setuptools.command.develop import develop
 from setuptools.command.install import install
 
 
@@ -144,6 +145,14 @@ def get_arch():
         return f"{machine}-{system}"
 
 
+class CustomDevelop(develop):
+
+    def run(self):
+        """Wrapper class to run the installation also when using `python setup.py develop`"""
+        self.run_command("install")
+        develop.run(self)
+
+
 with open("requirements.txt", "r", encoding="utf-8") as f:
     requirements = f.read().splitlines()
 
@@ -226,6 +235,10 @@ def read_description(*names, **kwargs) -> str:
             "haddock3-restraints = haddock.clis.cli_restraints:maincli",
         ]
     },
-    cmdclass={"build_ext": CustomBuild, "install": CustomInstall},
+    cmdclass={
+        "build_ext": CustomBuild,
+        "install": CustomInstall,
+        "develop": CustomDevelop,
+    },
     ext_modules=cpp_extensions,
 )

From 7ce504ef688a6a341176b5d9a60ae3ad6466af9e Mon Sep 17 00:00:00 2001
From: Rodrigo V Honorato <r.vargashonorato@uu.nl>
Date: Tue, 24 Sep 2024 17:08:33 +0200
Subject: [PATCH 18/24] update ci.yml

---
 .github/workflows/ci.yml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index f7ac7a8bc..26d14a8ea 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -26,6 +26,9 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y openmpi-bin libopenmpi3 libopenmpi-dev
 
+      - name: install python dependencies
+        run: pip install -r requirements.txt
+
       - name: install test dependencies
         run: >-
           pip install coverage pytest pytest-cov hypothesis pytest-mock mypy

From bb08c7868bae85f171ca0ede0526784576351e89 Mon Sep 17 00:00:00 2001
From: Rodrigo V Honorato <r.vargashonorato@uu.nl>
Date: Tue, 24 Sep 2024 17:08:46 +0200
Subject: [PATCH 19/24] update development instructions

---
 DEVELOPMENT.md | 33 ++++++++++++++++++---------------
 1 file changed, 18 insertions(+), 15 deletions(-)

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index e6181b6b4..bd1c45c63 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -72,30 +72,33 @@ We recommend you use Python's native virtual environment to manage the dependenc
 source .venv/bin/activate
 ```
 
-### Install haddock3 in development mode.
-
-```bash
-python setup.py develop
-```
-
 ### Install test dependencies
 
 Install both project dependencies and test dependencies using pip.
 
 ```bash
-pip install \
-   coverage==7.2.5 \
-   pytest==7.3.1 \
-   pytest-cov==4.0.0 \
-   hypothesis==6.75.1 \
-   pytest-mock==3.12.0 \
-   fastapi==0.110.1 \
-   httpx==0.27.0 \
-   mpi4py==3.1.6
+pip install -r requirements.txt &&
+    pip install \
+       coverage==7.2.5 \
+       pytest==7.3.1 \
+       pytest-cov==4.0.0 \
+       hypothesis==6.75.1 \
+       pytest-mock==3.12.0 \
+       fastapi==0.110.1 \
+       httpx==0.27.0 \
+       mpi4py==3.1.6
 ```
 
 > If you are using a Mac, if the installation of mpi4py fails, run first `brew install mpi4py`
 
+### Install haddock3 in development mode.
+
+In this mode the files are linked to the appropriate paths inside the python environment;
+
+```bash
+python setup.py develop
+```
+
 ## Installation in an HPC environment
 
 **Please get in contact with the system administrator before doing development in a shared HPC environment.**

From 245b1bbd128fb4ef00162a307e249adb343ce83d Mon Sep 17 00:00:00 2001
From: Rodrigo V Honorato <r.vargashonorato@uu.nl>
Date: Tue, 24 Sep 2024 17:20:06 +0200
Subject: [PATCH 20/24] update `docs.yml`

---
 .github/workflows/docs.yml | 13 ++++++++++++-
 io.json                    |  4 ++++
 2 files changed, 16 insertions(+), 1 deletion(-)
 create mode 100644 io.json

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index e6fc6d62d..b82eb34be 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -1,3 +1,6 @@
+# ===================================================================================#
+# FIXME: Rework this action after release!
+# ===================================================================================#
 name: docs
 
 on:
@@ -21,8 +24,16 @@ jobs:
           python -m pip install pip==23.1.2 setuptools==67.7.2 wheel==0.40.0
           pip install virtualenv==20.23.0 tox==4.5.1.1
 
+      - name: install python dependencies
+        run: pip install -r requirements.txt
+
+      - name: install test dependencies
+        run: >-
+          pip install coverage pytest pytest-cov hypothesis pytest-mock mypy
+          fastapi==0.110.1 httpx==0.27.0 mpi4py==3.1.6
+
       - name: install haddock3
-        run: pip install -v .
+        run: python setup.py -v develop
 
       - name: docs
         run: tox -e docs
diff --git a/io.json b/io.json
new file mode 100644
index 000000000..0caacb26a
--- /dev/null
+++ b/io.json
@@ -0,0 +1,4 @@
+{
+    "input": [],
+    "output": []
+}
\ No newline at end of file

From 315b3599b424575d0a67f346147d98bcca2052ca Mon Sep 17 00:00:00 2001
From: Rodrigo V Honorato <r.vargashonorato@uu.nl>
Date: Tue, 24 Sep 2024 17:33:39 +0200
Subject: [PATCH 21/24] update actions

---
 .github/workflows/ci.yml   |  5 +++++
 .github/workflows/docs.yml | 39 --------------------------------------
 2 files changed, 5 insertions(+), 39 deletions(-)
 delete mode 100644 .github/workflows/docs.yml

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 26d14a8ea..a120552cf 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -66,3 +66,8 @@ jobs:
         with:
           project-token: ${{ secrets.CODACY_PROJECT_TOKEN }}
           coverage-reports: ./coverage.xml
+
+      - name: check if docs are buildable
+        # this step can fail
+        continue-on-error: true
+        run: tox -e docs
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
deleted file mode 100644
index b82eb34be..000000000
--- a/.github/workflows/docs.yml
+++ /dev/null
@@ -1,39 +0,0 @@
-# ===================================================================================#
-# FIXME: Rework this action after release!
-# ===================================================================================#
-name: docs
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v2
-
-      - uses: actions/setup-python@v2
-        with:
-          python-version: 3.9
-
-      - name: Install dependencies
-        run: |
-          python -m pip install pip==23.1.2 setuptools==67.7.2 wheel==0.40.0
-          pip install virtualenv==20.23.0 tox==4.5.1.1
-
-      - name: install python dependencies
-        run: pip install -r requirements.txt
-
-      - name: install test dependencies
-        run: >-
-          pip install coverage pytest pytest-cov hypothesis pytest-mock mypy
-          fastapi==0.110.1 httpx==0.27.0 mpi4py==3.1.6
-
-      - name: install haddock3
-        run: python setup.py -v develop
-
-      - name: docs
-        run: tox -e docs

From 4c6ecd8f2463e661934b7020f63a5e1c66f89ffd Mon Sep 17 00:00:00 2001
From: Rodrigo V Honorato <r.vargashonorato@uu.nl>
Date: Tue, 24 Sep 2024 17:40:50 +0200
Subject: [PATCH 22/24] remove artifact

---
 io.json | 4 ----
 1 file changed, 4 deletions(-)
 delete mode 100644 io.json

diff --git a/io.json b/io.json
deleted file mode 100644
index 0caacb26a..000000000
--- a/io.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
-    "input": [],
-    "output": []
-}
\ No newline at end of file

From 40fad57d04358146fa7c7fcbdde7508dd3c42823 Mon Sep 17 00:00:00 2001
From: Rodrigo V Honorato <r.vargashonorato@uu.nl>
Date: Tue, 24 Sep 2024 17:42:31 +0200
Subject: [PATCH 23/24] tweak

---
 DEVELOPMENT.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index bd1c45c63..4df5d9c8f 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -72,7 +72,7 @@ We recommend you use Python's native virtual environment to manage the dependenc
 source .venv/bin/activate
 ```
 
-### Install test dependencies
+### Install python dependencies
 
 Install both project dependencies and test dependencies using pip.
 
@@ -99,14 +99,6 @@ In this mode the files are linked to the appropriate paths inside the python env
 python setup.py develop
 ```
 
-## Installation in an HPC environment
-
-**Please get in contact with the system administrator before doing development in a shared HPC environment.**
-
-For installation in an HPC environment we recommend to check the installed Python versions on the system and also importantly if an `openmpi` (or other custom MPI) installation is available on the system.
-Those are often offered via the `module` command.
-If you only intend to develop haddock3 using the multiprocessing scheduler, the above instructions should be fine. But to harvest the MPI capabilities of an HPC system it is best to build haddock3 using the installed MPI version on the HPC system.
-
 ## Running tests
 
 In `haddock3` we use the pytest framework, the tests are located in `tests/` (unit) and `integration_tests/` directories.
@@ -114,3 +106,11 @@ In `haddock3` we use the pytest framework, the tests are located in `tests/` (un
 ```bash
 pytest
 ```
+
+## Installation in an HPC environment
+
+**Please get in contact with the system administrator before doing development in a shared HPC environment.**
+
+For installation in an HPC environment we recommend to check the installed Python versions on the system and also importantly if an `openmpi` (or other custom MPI) installation is available on the system.
+Those are often offered via the `module` command.
+If you only intend to develop haddock3 using the multiprocessing scheduler, the above instructions should be fine. But to harvest the MPI capabilities of an HPC system it is best to build haddock3 using the installed MPI version on the HPC system.

From fc175373e1651b1854b285f0cf00bbc36ccc47c5 Mon Sep 17 00:00:00 2001
From: amjjbonvin <alexandre.bonvin@gmail.com>
Date: Tue, 24 Sep 2024 19:26:59 +0200
Subject: [PATCH 24/24] Removed full path to python3.9 The exact path might
 vary depending on the system/installation

---
 DEVELOPMENT.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index 4df5d9c8f..729fd488e 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -68,7 +68,7 @@ cd haddock3
 We recommend you use Python's native virtual environment to manage the dependencies.
 
 ```bash
-/usr/local/bin/python3.9 -m venv .venv
+python3.9 -m venv .venv
 source .venv/bin/activate
 ```