Add user-guide (#8)

* add book stub

* add guide

* add mdbook.yml

.github/workflows/mdbook.yml

@@ -0,0 +1,58 @@
+name: deploy mdBook site
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: main
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch: ~
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    env:
+      MDBOOK_VERSION: 0.4.36
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install mdBook
+        run: |
+          curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh
+          rustup update
+          cargo install --version ${MDBOOK_VERSION} mdbook
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v4
+
+      - name: Build with mdBook
+        run: mdbook build docs
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs/book
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,2 +1,3 @@
 /target
-.vscode
+.vscode
+docs/book

docs/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["Rodrigo V Honorato"]
+language = "en"
+multilingual = false
+src = "src"
+title = "haddock-restraints"

docs/src/SUMMARY.md

@@ -0,0 +1,12 @@
+# Summary
+
+- [Home](./home.md)
+- [Installation](./installation.md)
+- [Usage](./usage.md)
+  - [`tbl`](./tbl.md)
+    - [Active/Passive](./active_passive.md)
+    - [Configuration file](./configuration_file.md)
+  - [`ti`](./ti.md)
+  - [`restraint`](./restraint.md)
+  - [`interface`](./interface.md)
+- [Development](./development.md)

docs/src/active_passive.md

@@ -0,0 +1,53 @@
+
+# Active/Passive residues
+
+We have a deeper explanation of these at our [Best Practice Guide](https://www.bonvinlab.org/software/bpg/restraints/) - but for brevity , we can say that:
+
+- Active residues **MUST** be in contact with the other molecule.
+- Passive residues **COULD** be in contact with the other molecule.
+
+Let's say you have two proteins A and B; for protein A, you have very high confidence, _based on your experiments, in information retrieved from the literature or bioinformatic predictions_ that residue number 950 is very important for the interaction.
+
+However for protein B you do not know the exact residues involved in the interaction, but you know that the interaction happens in a specific region of the protein. Let's say this region is between residues 41 and 45.
+
+In this example, your active residues are:
+
+- Protein A: 950
+- Protein B: 41, 42, 43, 44, 45
+
+For your passive residues, you can select a region **around** your active residues to serve as the passive residues. This is a way to tell the docking software that these residues are not as important as the active ones, but they could be in contact with the other molecule.
+
+> You can do the passive selection manually, by visual inspection or `haddock-restraints` can do it automatically for you, using the `passive_from_active` option.
+
+In the end, your configuration file will look like this:
+
+```json
+[
+  {
+    "id": 1,
+    "chain": "A",
+    "active": [950],
+    "passive": [],
+    "structure": "proteinA.pdb",
+    "passive_from_active": true,
+    "target": [2]
+  },
+  {
+    "id": 2,
+    "chain": "B",
+    "active": [41, 42, 43, 44, 45],
+    "passive": [],
+    "structure": "proteinB.pdb",
+    "passive_from_active": true,
+    "target": [1]
+  }
+]
+```
+
+Visually, the restraints generated by this configuration file will look like this:
+
+| Protein A      | Protein B      |
+| ------------- | ------------- |
+| ![tbl_1](./tbl_1.png) | ![tbl_2](./tbl_2.png) |
+
+> Active residues are in red, and the passive residues are in yellow.

docs/src/configuration_file.md

@@ -0,0 +1,142 @@
+# `tbl` configuration file
+
+Restraints are very powerful tools to guide the docking process, to use its full potential, in `haddock-restraints` we use a configuration file to define the restraints. This file is a JSON file that contains the information needed to generate the restraints.
+
+To use the full potential of ambiguous restraints we have introduced the concept of _interactors_, which are arbitrary groups of residues that can be used to define the restraints.
+
+`haddock-restraints` supports an unlimited number of interactors, and each interactor can have an unlimited number of residues. This allows you to define complex restraints that can be used to guide the docking process.
+
+- [Mandatory fields](#mandatory-fields)
+- [Optional fields](#optional-fields)
+- [Reference guide](#reference-guide) with detailed explanation of the fields in the configuration file
+
+***
+
+## Mandatory fields
+
+- `id`: an integer that identifies the interactor
+- `chain`: the chain of the interactor
+- `active`: a list of residues that are active in the interaction
+- `passive`: a list of residues that are passive in the interaction
+- `target`: a list of integers that identifies the interactors that the current interactor interacts with
+
+A minimal configuration file would look like this:
+
+```json
+[
+  {
+    "id": 1,
+    "chain": "A",
+    "active": [950],
+    "passive": [],
+    "target": [2]
+  },
+  {
+    "id": 2,
+    "chain": "B",
+    "active": [41, 42, 43, 44, 45],
+    "passive": [],
+    "target": [1]
+  }
+]
+```
+
+## Optional fields
+
+- `structure`: the PDB file that contains the structure of the interactor
+- `passive_from_active`: if true, the passive residues are defined based on the active residues (_requires structure_)
+- `surface_as_passive`: if true, the passive residues are defined based on the surface accessibility of the residues (_requires structure_)
+- `filter_buried`: if true, the buried residues are filtered out (_requires structure_)
+- `filter_buried_cutoff`: the cutoff to consider a residue as buried, default = 0.7 (_requires structure_)
+
+A configuration file with optional fields would look like this:
+
+```json
+[
+  {
+    "id": 1,
+    "chain": "A",
+    "active": [
+      934,
+      939
+    ],
+    "passive": [],
+    "structure": "2oob.pdb",
+    "target": [
+      2
+    ],
+    "passive_from_active": true,
+    "filter_buried": true
+  },
+  {
+    "id": 2,
+    "chain": "B",
+    "active": [
+      68
+    ],
+    "passive": [],
+    "target": [
+      1
+    ]
+  },
+  {
+    "id": 3,
+    "chain": "B",
+    "active": [],
+    "passive": [],
+    "target": [
+      1
+    ],
+    "structure": "2oob.pdb",
+    "surface_as_passive": true
+  }
+]
+```
+
+## Reference guide
+
+- `id`
+  - type: integer
+  - description: an integer that identifies the interactor
+
+- `chain`
+  - type: string
+  - description: the chain of the interactor
+
+- `active`
+  - type: list of integers
+  - description: a list of residues that are active in the interaction
+
+- `passive`
+  - type: list of integers
+  - description: a list of residues that are passive in the interaction
+
+- `target`
+  - type: list of integers
+  - description: a list of integers that identifies the interactors that the current interactor interacts with
+
+Optional fields are:
+
+- `structure`
+  - type: string
+  - description: the PDB file that contains the structure of the interactor. If using relative paths, they should be relative to the configuration file
+
+- `passive_from_active`
+  - type: boolean
+  - description: define passive residues are defined based on the active residues
+  - requires: `structure`
+
+- `surface_as_passive`
+  - type: boolean
+  - description: define passive residues are defined based on the surface accessibility of the residues
+  - requires: `structure`
+
+- `filter_buried`
+  - type: boolean
+  - description: filter out buried residues
+  - requires: `structure`
+
+- `filter_buried_cutoff`
+  - type: float
+  - description: the cutoff to consider a residue as buried, default = 0.7
+  - requires: `structure`

docs/src/development.md

@@ -0,0 +1,5 @@
+# Development
+
+`haddock-restraints` is an open-source project. You can contribute to the project by submitting issues, feature requests, or pull requests.
+
+Please go to the [GitHub repository](https://github.com/haddocking/haddock-restraints) to open an issue or submit a pull request.

docs/src/home.md

@@ -0,0 +1,17 @@
+# Welcome to the `haddock-restraints` guide
+
+![image](./banner_home-mini.jpg)
+
+`haddock-restraints` is a command-line tool that helps you to generate restraints for the HADDOCK docking software.
+
+The generation of restraints is a crucial step in the preparation of a docking experiment. The restraints define the spatial constraints that guide the docking software in the search for the best conformation of the complex.
+
+[HADDOCK](https://www.bonvinlab.org/software/#haddock) uses a `.tbl` format to define the restraints. If you are using the [web service](https://wenmr.science.uu.nl), these are defined automatically via the web interface. However, if you are running HADDOCK locally, you need to provide these restraints yourself.
+
+This is where `haddock-restraints` comes in. It helps you to generate the restraints in the `.tbl` format, based on the input structures you provide.
+
+See the [INSTALLATION](./installation.md) section to get started and proceed to the [USAGE](./usage.md) section to learn how to use the tool.
+
+## Getting help
+
+If you encounter any issues or have any questions, please open an issue on the [GitHub repository](https://github.com/haddocking/haddock-restraints), contact us at _[email protected]_ or join the [BioExcel forum](https://ask.bioexcel.eu) and post your question there.

docs/src/installation.md

@@ -0,0 +1,29 @@
+# Installation
+
+`haddock-restraints` is a Rust command-line tool. To install it, you need to have the Rust toolchain installed on your system. You can install Rust by following the instructions on the [official website](https://www.rust-lang.org/tools/install).
+
+It is also published in [Crates.io](https://crates.io/crates/haddock-restraints), so you can install it using the following command using Cargo, the Rust package manager:
+
+```bash
+cargo install haddock-restraints
+```
+
+Now it should be available in your system. You can check if it is installed by running:
+
+```bash
+haddock-restraints -h
+```
+
+## From source
+
+If you prefer to install it from source, you can clone the repository and build it using Cargo:
+
+```bash
+git clone https://github.com/haddocking/haddock-restraints
+cd haddock-restraints
+cargo build --release
+```
+
+***
+
+Go ahead and proceed to the [USAGE](./usage.md) section to learn how to use the tool.

docs/src/interface.md

@@ -0,0 +1,13 @@
+# List residues in the interface
+
+This command is a helpful when you want to know which residues are in the interface of a protein-protein complex. It calculates the distance between the residues of two chains and if the distance is less than a given cutoff, the residues are considered to be in the interface.
+
+> The result of this might be useful to generate restraints using the [`tbl` command](./tbl.md) - to define active and/or passive residues.
+
+## Usage
+
+To run the `interface` subcommand, you just need to provide the path to the PDB file and the cutoff distance. For example:
+
+```bash
+haddock-restraints interface path/to/complex.pdb 5.0
+```

docs/src/restraint.md

@@ -0,0 +1,13 @@
+# Generate unambiguous restraints to keep molecules together during docking
+
+In some scenarios, you might be docking proteins that contain **structural gaps**, but you still want to keep the molecules together during the docking process. This is where the `restraint` subcommand comes in handy.
+
+It will generate **unambiguous restraints** to keep the molecules together during docking.
+
+## Usage
+
+To run the `restraint` subcommand, you just need to provide the path to the PDB file. For example:
+
+```bash
+haddock-restraints restraint path/to/complex.pdb > unambig.tbl
+```

docs/src/tbl.md

@@ -0,0 +1,17 @@
+# Generate `.tbl` file from a configuration file
+
+`haddock-restraints` can generate a `.tbl` file from a configuration file. The configuration file is a JSON file that contains the information needed to generate the restraints.
+
+To use this file you first need to get familiar with a few concepts:
+
+- [Active/Passive residues](./active_passive.md)
+
+- [Configuration file](./configuration_file.md)
+
+## Usage
+
+To run the `tbl` subcommand, you just need to provide the path to the configuration file. For example:
+
+```bash
+haddock-restraints tbl path/to/config.json > restraints.tbl
+```

docs/src/ti.md

@@ -0,0 +1,15 @@
+# Generate _true-interface_ restraints from a PDB file
+
+This is a very specific type of restraint, that is used to restrain the interface of a protein-protein complex most commonly used to benchmark the efficiency of a docking workflow or protocol.
+
+What this command does is to calculate the distance between the residues of two chains and if the distance is less than a given cutoff, the residues are considered to be in the interface.
+
+Based on this, `haddock-restraints` fills in the `active` and `passive` fields and provides you with a `.tbl` file that can be used to restrain the interface of the protein-protein complex.
+
+## Usage
+
+To run the `ti` subcommand, you just need to provide the path to the PDB file and the cutoff distance. For example:
+
+```bash
+haddock-restraints ti path/to/complex.pdb 5.0 > ti.tbl
+```