Skip to content

Enable Sphinx API documentation from docstrings; Use sphinx-argparse-cli to generate documentation for CLI scripts#357

Open
rwxayheee wants to merge 67 commits intoforlilab:developfrom
rwxayheee:api-docstring
Open

Enable Sphinx API documentation from docstrings; Use sphinx-argparse-cli to generate documentation for CLI scripts#357
rwxayheee wants to merge 67 commits intoforlilab:developfrom
rwxayheee:api-docstring

Conversation

@rwxayheee
Copy link
Copy Markdown
Contributor

@rwxayheee rwxayheee commented May 3, 2025

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

  • covalentbuilder
    the 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

@rwxayheee rwxayheee marked this pull request as draft May 5, 2025 22:38
@rwxayheee rwxayheee marked this pull request as ready for review May 7, 2025 08:52
@rwxayheee
Copy link
Copy Markdown
Contributor Author

rwxayheee commented May 7, 2025

###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.

@rwxayheee rwxayheee marked this pull request as draft May 7, 2025 20:23
@rwxayheee rwxayheee changed the title Enable Sphinx API documentation from docstrings Enable Sphinx API documentation from docstrings; Use sphinx-argparse-cli to generate documentation for CLI scripts May 7, 2025
@rwxayheee rwxayheee marked this pull request as ready for review May 7, 2025 21:19
@rwxayheee
Copy link
Copy Markdown
Contributor Author

rwxayheee commented May 7, 2025

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
mk_prepare_ligand.py CLI Reference
mk_export.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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant