Improved online documentation

CHANGELOG.md

@@ -1,5 +1,6 @@
 # Changelog
 
+- 2026-04-08: Improved docstring in modules
 - 2026-04-08: Increased NOE restraints array size in scoring modules - Issue #1501
 - 2026-03-09: Automated type casting for optional argument seed in haddock3-restraints random_removal - Issue #1485
 - 2026-02-28: Switched to ilRMSD clustering from protein-ligand examples - Issue #1481

devtools/build_defaults_rst.py

@@ -43,7 +43,7 @@
     "sasascore": "Surface Accessibility Scoring module",
     "prodigyprotein": "Binding affinity prediction with PRODIGY",
     "prodigyligand": "Ligand binding affinity prediction with PRODIGY-lig",
-    "filter": "Filtering of models based on their score",
+    "filter": "Filtering module",
 }
 
 CATEGORY_TITLE_DICT = {

src/haddock/modules/_template_cat/_template_mod/__init__.py

@@ -11,6 +11,10 @@
 You should use restructureText syntax:
 
     https://docutils.sourceforge.io/docs/user/rst/quickstart.html
+
+End this module docstring by providing a link to the haddock3-user-manual. e.g:
+For more details about this module, please `refer to the haddock3 user manual
+<https://www.bonvinlab.org/haddock3-user-manual/modules/topology.html#topoaa-module>`_
 """
 # Import here what you need
 from pathlib import Path

src/haddock/modules/analysis/alascan/__init__.py

@@ -40,6 +40,9 @@
 
     >>> resdic_A = [1,2,3,4]
     >>> resdic_B = [2,3,4]
+
+For more details about this module, please `refer to the haddock3 user manual
+<https://www.bonvinlab.org/haddock3-user-manual/modules/analysis.html#alascan-module>`_
 """
 
 from pathlib import Path

src/haddock/modules/analysis/caprieval/__init__.py

@@ -23,6 +23,9 @@
 
 - **capri_ss.tsv**: a table with the CAPRI metrics for each model.
 - **capri_clt.tsv**: a table with the CAPRI metrics for each cluster of models (if clustering information is available).
+
+For more details about this module, please `refer to the haddock3 user manual
+<https://www.bonvinlab.org/haddock3-user-manual/modules/analysis.html#caprieval-module>`_
 """
 
 

src/haddock/modules/analysis/clustfcc/__init__.py

@@ -4,10 +4,13 @@
 contacts between them. Then, the module calculates the FCC matrix and clusters
 the models based on their contact similarities.
 
-For more details please check
+For more details about this clustering method, please check
 *Rodrigues, J. P. et al.
 Proteins: Struct. Funct. Bioinform.
 80, 1810–1817 (2012)*
+
+For more details about this module, please `refer to the haddock3 user manual
+<https://www.bonvinlab.org/haddock3-user-manual/modules/analysis.html#clustfcc-module>`_
 """
 
 import os

src/haddock/modules/analysis/clustrmsd/__init__.py

@@ -17,17 +17,19 @@
 * `n_clusters`: number of desired clusters (if `criterion` is `maxclust`).
 * `clust_cutoff`: value of distance that separates distinct clusters (if `criterion` is
   ``distance``)
-* `min_population` : analogously to the `clustfcc` module, it is the minimum number
-  of models that should be present in a cluster to consider it. If criterion is
-  `maxclust`, the value is ignored.
+* `min_population` : set the minimum number of models that should be present
+  in a cluster to consider it. If criterion is `maxclust`, the value is ignored.
 
 This module passes the path to the RMSD matrix is to the next step of the
 workflow through the `rmsd_matrix.json` file, thus allowing to execute several
 `clustrmsd` modules (possibly with different parameters) on the same RMSD
 matrix.
 
 .. _scipy routines: https://docs.scipy.org/doc/scipy/reference/cluster.hierarchy.html
-"""  # noqa: E501
+
+For more details about this module, please `refer to the haddock3 user manual
+<https://www.bonvinlab.org/haddock3-user-manual/modules/analysis.html#clustrmsd-module>`_
+"""
 from pathlib import Path
 
 from haddock import log

src/haddock/modules/analysis/contactmap/__init__.py

@@ -11,6 +11,9 @@
 
 **Chordcharts** are describing only intermolecular contacts in circles,
 connecting with *chords* the two residues that are contacting.
+
+For more details about this module, please `refer to the haddock3 user manual
+<https://www.bonvinlab.org/haddock3-user-manual/modules/analysis.html#contactmap-module>`_
 """
 
 from copy import deepcopy

src/haddock/modules/analysis/filter/__init__.py

@@ -1,16 +1,25 @@
-"""Filter models based on their score.
+"""Filtering module.
 
-This module filters the input models based on their score using a threshold
-value. Models having higher score than the threshold value are filtered out.
+The ``[filter]`` module filters the input models based on their score using a
+``threshold`` value.
+Models having higher score than the threshold value are filtered out.
 
 The number of models to be selected is unknown, and is the set of models that
-have a score below the defined threshold.
-For this module to be functional, a score must be first computed. This can be
-performed by running a CNS module or a scoring module. If scores are not
-accessible, the workflow will terminate with an error message.
+have a **score below the defined threshold**.
 
-If the threshold value is too stringent, resulting in no models passed to the
-next module, the workflow will stop with an error message.
+**Important**:
+For this module to be functional, a score must be first computed.
+This can be performed by running a CNS module or a scoring module.
+
+**Program termination cases**:
+
+* If scores are not
+  accessible, the workflow will terminate with an error message.
+* If the threshold value is too stringent, resulting in no models passed to the
+  next module, the workflow will stop with an error message.
+
+For more details about this module, please `refer to the haddock3 user manual
+<https://www.bonvinlab.org/haddock3-user-manual/modules/analysis.html#filter-module>`_
 """
 
 from pathlib import Path

src/haddock/modules/analysis/ilrmsdmatrix/__init__.py

@@ -14,6 +14,9 @@
 IMPORTANT: the module assumes coherent numbering for all the receptor and ligand
 chains, as no alignment is performed. The user must ensure that the numbering
 is coherent.
+
+For more details about this module, please `refer to the haddock3 user manual
+<https://www.bonvinlab.org/haddock3-user-manual/modules/analysis.html#ilrmsdmatrix-module>`_
 """
 
 import os

src/haddock/modules/analysis/rmsdmatrix/__init__.py

@@ -24,6 +24,9 @@
 
 thus telling the module to consider residues from 1 to 4 of chain A and from 2
 to 4 of chain B for the alignment and RMSD calculation.
+
+For more details about this module, please `refer to the haddock3 user manual
+<https://www.bonvinlab.org/haddock3-user-manual/modules/analysis.html#rmsdmatrix-module>`_
 """
 
 import contextlib

src/haddock/modules/analysis/seletop/__init__.py

@@ -6,6 +6,9 @@
 The number of models to be selected is defined by the parameter `select`.
 In the standard HADDOCK protocol, this number is 200, which can be increased
 if more models should be refined.
+
+For more details about this module, please `refer to the haddock3 user manual
+<https://www.bonvinlab.org/haddock3-user-manual/modules/analysis.html#seletop-module>`_
 """
 from pathlib import Path
 

src/haddock/modules/analysis/seletopclusts/__init__.py

@@ -7,6 +7,9 @@
 are shown. In case seletopclusts is run after a sampling module, we can
 keep a few models from all the clusters to have more diversity at the
 refinement stage(s).
+
+For more details about this module, please `refer to the haddock3 user manual
+<https://www.bonvinlab.org/haddock3-user-manual/modules/analysis.html#seletopclusts-module>`_
 """
 
 from pathlib import Path

src/haddock/modules/refinement/emref/__init__.py

@@ -5,6 +5,9 @@
 
 Coordinates of the energy minimized structures are saved, and each
 complex is then evaluated using the HADDOCK scoring function.
+
+For more details about this module, please `refer to the haddock3 user manual
+<https://www.bonvinlab.org/haddock3-user-manual/modules/refinement.html#emref-module>`_
 """
 
 from pathlib import Path

src/haddock/modules/refinement/flexref/__init__.py

@@ -19,6 +19,9 @@
 body molecular dynamics on.
 
 The temperature and number of steps for the various stages can be tuned.
+
+For more details about this module, please `refer to the haddock3 user manual
+<https://www.bonvinlab.org/haddock3-user-manual/modules/refinement.html#flexref-module>`_
 """
 
 from pathlib import Path

src/haddock/modules/refinement/mdref/__init__.py

@@ -7,17 +7,20 @@
 surface residues.
 
 The `mdref` protocol is composed of 4 sequential steps:
-- Short energy minimization
-- 3 stages of molecular dynamics to reach 300K (at 100, 200 and 300K)
-- Molecular dynamics at 300K.
-- 3 stages of molecular dynamics, to reach 100K (at 300, 200 and 100K)
+1. Short energy minimization
+2. 3 stages of molecular dynamics to reach 300K (at 100, 200 and 300K)
+3. Molecular dynamics at 300K.
+4. 3 stages of molecular dynamics, to reach 100K (at 300, 200 and 100K)
 
 Using this protocol, with default parameters, no spectacular changes are
 expected, however, the scoring of the various structures might be improved.
 
 
 Number of MD steps can be modified using the ``waterheatsteps``, ``watersteps``
 and ``watercoolsteps``.
+
+For more details about this module, please `refer to the haddock3 user manual
+<https://www.bonvinlab.org/haddock3-user-manual/modules/refinement.html#mdref-module>`_
 """
 
 from pathlib import Path

src/haddock/modules/refinement/openmm/__init__.py

@@ -26,6 +26,9 @@
 such as `flexref` or `emref` after the OpenMM module, you need to recreate the
 topologies by simply adding a `[topoaa]` step in the workflow.
 See examples in `examples/thirdparty/openmm` folder.
+
+For more details about this module, please `refer to the haddock3 user manual
+<https://www.bonvinlab.org/haddock3-user-manual/modules/refinement.html#openmm-module>`_
 """
 import os
 import shutil

src/haddock/modules/sampling/lightdock/__init__.py

@@ -1,4 +1,8 @@
-"""LightDock integration sampling module."""
+"""LightDock integration sampling module.
+
+For more details about this module, please `refer to the haddock3 user manual
+<https://www.bonvinlab.org/haddock3-user-manual/modules/sampling.html#lightdock-module>`_
+"""
 import shutil
 import subprocess
 from pathlib import Path

src/haddock/modules/sampling/rigidbody/__init__.py

@@ -27,6 +27,9 @@
 much better and the sampling can be limited. In *ab-initio* mode, however, very
 diverse solutions will be obtained and the sampling should be increased to make
 sure to sample enough the possible interaction space.
+
+For more details about this module, please `refer to the haddock3 user manual
+<https://www.bonvinlab.org/haddock3-user-manual/modules/sampling.html#rigidbody-module>`_
 """
 
 from pathlib import Path

src/haddock/modules/scoring/emscoring/__init__.py

@@ -2,6 +2,9 @@
 
 This module performs energy minimization and scoring of the models generated in
 the previous step of the workflow. No restraints are applied during this step.
+
+For more details about this module, please `refer to the haddock3 user manual
+<https://www.bonvinlab.org/haddock3-user-manual/modules/scoring.html#emscoring-module>`_
 """
 
 from pathlib import Path

src/haddock/modules/scoring/mdscoring/__init__.py

@@ -2,6 +2,9 @@
 
 This module will perform a short MD simulation on the input models and
 score them. No restraints are applied during this step.
+
+For more details about this module, please `refer to the haddock3 user manual
+<https://www.bonvinlab.org/haddock3-user-manual/modules/scoring.html#mdscoring-module>`_
 """
 
 from pathlib import Path

src/haddock/modules/scoring/prodigyligand/__init__.py

@@ -3,6 +3,9 @@
 This module performs the scoring of input complexes using PRODIGY-ligand.
 It predicts deltaG of the complex and can return predictions as either deltaG
 or pKd values.
+
+For more details about this module, please `refer to the haddock3 user manual
+<https://www.bonvinlab.org/haddock3-user-manual/modules/scoring.html#prodigyligand-module>`_
 """
 
 from pathlib import Path

src/haddock/modules/scoring/prodigyprotein/__init__.py

@@ -5,6 +5,9 @@
 or pKd values.
 
 Note that PRODIGY-protein is limited to natural amino-acids.
+
+For more details about this module, please `refer to the haddock3 user manual
+<https://www.bonvinlab.org/haddock3-user-manual/modules/scoring.html#prodigyprotein-module>`_
 """
 
 from pathlib import Path

src/haddock/modules/topology/topoaa/__init__.py

@@ -19,8 +19,22 @@
 and carbohydrates ... see `detailed list of supported molecules
 <https://wenmr.science.uu.nl/haddock2.4/library>`_),
 such as small-molecules, parameters and topology must be obtained and provided
-by the user, as there is currently no built-in solution to generate
-them on the fly.
+by the user, using `ligand_param_fname` and `ligand_top_fname` parameters.
+If you do not have them, they can be generated on-the-fly by setting
+the `autotoppar` parameter to `true`.
+
+To define specific parameters for a given molecule (charge of terminis,
+histidine protonations, peptide cyclisation, ...), you should re-define
+a quasi topoaa module and specify the molecule index, right after
+the ``[topoaa]`` module. e.g.:
+
+``
+[topoaa]
+[topoaa.mol1]
+``
+
+For more details about this module, please `refer to the haddock3 user manual
+<https://www.bonvinlab.org/haddock3-user-manual/modules/topology.html#topoaa-module>`_
 """
 
 import operator