Enable Sphinx API documentation from docstrings; Use sphinx-argparse-cli to generate documentation for CLI scripts#357
Conversation
|
###Summary 1. Added missing docstring and API documentation for important potentially useful modules for object manipulation, data extraction and modeling analysis:
2. Some constants are ignored on purpose, for example:meeko.rdkit_mol_create module
========================
.. autoclass:: meeko.rdkit_mol_create.RDKitMolCreate
:members:
:show-inheritance:
:exclude-members: ambiguous_flexres_choices, flexres
3. The build environment for the documentation does not require package dependencies (because it's a bit tricky with ProDy at this moment). This is enabled by:autodoc_mock_imports = [
"rdkit", "rdkit.Chem", "rdkit.Geometry", "numpy", "scipy", "gemmi", "prody"
]Some minor changes might be needed for PRs that are currently pending review or future changes. |
for mk_prepare_receptor.py using sphinx_argparse_cli
|
The edits after the last comment enabled the dynamic generation of documentation for the CLI scripts, which should be better and easier to maintain than the premade ones. To enable this, some minor edits were made to the scripts. Preview: mk_prepare_receptor.py CLI Reference This PR is concluded but open to further edits. No PR is required to modify anything here. Please duplicate the branch or file and edit as needed. For clarity, the changes that require additional Sphinx build dependencies are put together in this PR. Some other updates to specific items that will appear in the changelog will be added in a separate PR. |
This PR sets up automatic generation of API documentation using Sphinx for module, class, and functions with proper numpy-style docstrings. The relatively stable submodule (chemtempgen, as no further updates are pending) is used as an example for preview:
https://apidocmeeko.readthedocs.io/en/latest/meeko.chemtempgen.html
It includes the minimal configuration in conf.py and lists all the .rst files to include relevant autodoc directives. As long as the module, class and functions are commented properly in the numpy-style (description, parameters, returns, raises, etc.) the documentation shall be auto-filled.
A similar documentation method is used in AutoDock Vina. This PR uses a small trick such that the building of the doc doesn't neccessarily require the package dependencies.
Add numpy-style docstring, format and index the auto-generated documentations for:
chemtempgen
covalentbuilderthe autodoc generation was not successful but I'm not fixing it (in many ways, the code is working but not in a good shape). As previously proposed in Refactor CovalentBuilder, Enable Custom Tether Atoms within Receptor, and Export Modified Polymer to PDB #277, this module should be refactored and would greatly benefit from becoming independent from prody and more flexible
polymer
preparation
molecule_pdbqt
molsetup
rdkit_mol_create
Selection and ordering
Use sphinx-argparse-cli to generate documentation for CLI scripts