Generate .rst documentation page for .yaml default configuration files

[joaomcteixeira]

You are about to submit a new Pull Request. Before continuing make sure you read the contributing guidelines and you comply with the following criteria:

• You have stick to Python. Talk with us before adding other programming languages to HADDOCK3
• Your PR is about CNS
• Your code is well documented: proper docstrings and explanatory comments for those tricky parts
• You structured the code into small functions as much as possible. You can use classes if there's a (state) purpose
• code follows our coding style
• You wrote tests for the new code
• tox tests pass. Run tox command inside the repository folder
• -test.cfg examples execute without errors. Inside examples/ run python run_tests.py -b
• PR does not add any install dependencies unless permission granted by the HADDOCK team
• PR does not break licensing
• Your PR is about writing documentation for already existing code 🔥
• Your PR is about writing tests for already existing code

---

Default parameters for each module, as well as general parameters and mandatory parameters, are defined in yaml files. However, these are not yet documented in the HD3 HTML doc pages.

In this PR I introduce a script in the devtools folder that generate local .rst pages with the documentation for the yaml files.

After you generate the docs locally: tox -e docs, you will find at the bottom of each module's documentation the yaml docs. Therefore, each module doc page will be composed of 3 sections:

1. a general description of the module, which is written in the __init__.py docstring for each module
2. the API documentation of the module
3. the default parameters documentation

In Reference -> Core there are also the mandatory parameters. And in the main module index page also the general module parameters.

Have a look and let me know your feelings. Obviously, it can be improved in the future. But I think the result is good. Btw, parameter names are heading meaning they can be clicked.

relevant note: we have parameters that are dictionaries, like mol1 in topoaa. This is okay. But the machinery here does not allow for more than one nesting level. Which I think is also a good human limit. Nothing to worry on this is just a note for the future.

[codecov-commenter]

Codecov Report

Merging #436 (40fc4ae) into main (088e998) will decrease coverage by 0.08%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##             main     #436      +/-   ##
==========================================
- Coverage   71.14%   71.06%   -0.09%     
==========================================
  Files          92       91       -1     
  Lines        5757     5737      -20     
==========================================
- Hits         4096     4077      -19     
+ Misses       1661     1660       -1     

Impacted Files	Coverage Δ
src/haddock/modules/analysis/caprieval/capri.py	78.72% <0.00%> (-13.34%)	⬇️
src/haddock/libs/libalign.py	65.64% <0.00%> (-4.28%)	⬇️
tests/test_module_caprieval.py	96.10% <0.00%> (-3.90%)	⬇️
src/haddock/libs/libontology.py	76.33% <0.00%> (-0.77%)	⬇️
tests/test_libio.py	100.00% <0.00%> (ø)
tests/test_libalign.py	100.00% <0.00%> (ø)
src/haddock/modules/analysis/caprieval/caprijob.py
src/haddock/modules/analysis/rmsdmatrix/rmsd.py	98.01% <0.00%> (+0.04%)	⬆️
src/haddock/libs/libio.py	84.12% <0.00%> (+11.90%)	⬆️
src/haddock/modules/analysis/caprieval/__init__.py	34.28% <0.00%> (+14.74%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 088e998...40fc4ae. Read the comment docs.

[joaomcteixeira]

Thanks. for the comments. You are right, I will address that.

[joaomcteixeira]

thanks @mgiulini for the very nice comments and shape catches. I have improved the script and added docs. Have a look.
Cheers,

[mgiulini]

Cool 👍