Correct docstrings to make them work with Sphinx

test


test2


test3

.readthedocs.yml

@@ -18,4 +18,7 @@ formats: all
 
 # Optionally set the version of Python and requirements required to build your docs
 conda:
-  environment: environment.yml
+  environment: environment.yml
+
+build:
+  image: stable

docs/source/conf.py

@@ -35,7 +35,6 @@
     'sphinx.ext.napoleon',  # support for NumPy and Google style docstrings
     'sphinx.ext.todo',  # include to do
     'sphinx.ext.coverage',
-    'sphinx_automodapi.automodapi'
 ]
 
 # Add any paths that contain templates here, relative to this directory.

rdmc/forcefield.py

@@ -23,15 +23,36 @@ class RDKitFF(object):
     """
     A wrapper to deal with Force field in RDKit.
     """
-    def __init__(self, force_field:str = 'mmff94s'):
+    def __init__(self, force_field: str = 'mmff94s'):
+        """
+        Initiate the ``RDKitFF`` by given the name of the force field.
+
+        Args:
+            force_field: The name of the force field. Supporting:
+                - MMFF94s (default)
+                - MMFF94
+                - UFF
+        """
         self.ForceField = force_field
 
     @property
     def ForceField(self):
+        """
+        Return the force field backend.
+        """
         return self._ff
 
     @ForceField.setter
     def ForceField(self, force_field):
+        """
+        Reset the force field backend.
+
+        Args:
+            force_field: The name of the force field. Supporting:
+                - MMFF94s (default)
+                - MMFF94
+                - UFF
+        """
         force_field = force_field.lower()
         if not force_field in ['mmff94s', 'mmff94', 'uff']:
             raise ValueError(f'RDKit does not support {force_field}')
@@ -58,13 +79,14 @@ def MakeOptimizable(self,
                         mol: 'RDKitMol',
                         inplace: bool = False):
         """
-        Make the molecule able to be optimized by the force field.
-        1. it is known that RO[O] is not optimizable by MMFF. By changing -O[O] to -OF,
+        Make the molecule able to be optimized by the force field. Known problematic molecules:
+
+        1. RO[O] is not optimizable by MMFF. By changing -O[O] to -OF,
            it allows the geometry to be optimized yielding reasonable results.
 
         Args:
             mol ('Mol'): Molecule to be changed.
-            inplace (bool, optional): Whether to make the change inplace. Defaults to False.
+            inplace (bool, optional): Whether to make the change inplace. Defaults to ``False``.
 
         Returns:
             ('Mol', dict): A modified molecule and approaches to modify this molecule.
@@ -110,7 +132,7 @@ def RecoverMol(self,
         Args:
             mol ('Mol'): Molecule to be changed.
             edits (dict): A dict of approach to modify this molecule
-            inplace (bool, optional): Whether to make the change inplace. Defaults to True.
+            inplace (bool, optional): Whether to make the change inplace. Defaults to ``True``.
 
         Returns:
             'Mol' A recovered molecule.
@@ -143,8 +165,8 @@ def _OptimizeConfs(self,
 
         Args:
             mol ('Mol'): A molecule to be optimized.
-            maxIters (int, optional): max iterations. Defaults to 200.
-            numThreads (int, optional): number of threads to use. Defaults to 0 for all.
+            maxIters (int, optional): max iterations. Defaults to ``200``.
+            numThreads (int, optional): number of threads to use. Defaults to ``0`` for all.
 
         Returns:
             - int: 0 for optimization done; 1 for not optimized; -1 for not optimizable.
@@ -175,10 +197,10 @@ def OptimizeConfs(self,
 
         Args:
             mol ('Mol'): A molecule to be optimized.
-            maxIters (int, optional): max iterations. Defaults to 200.
-            numThreads (int, optional): number of threads to use. Defaults to 0 for all.
+            maxIters (int, optional): max iterations. Defaults to ``200``.
+            numThreads (int, optional): number of threads to use. Defaults to ``0`` for all.
             maxCycles (int, optional): number of outer cycle. Check convergence after maxIters.
-                                       Defaults to 20.
+                                       Defaults to ``20``.
 
         Returns:
             - int: 0 for optimization done; 1 for not optimized; -1 for not optimizable.

rdmc/mol.py

@@ -43,10 +43,10 @@ class RDKitMol(object):
 
     def __init__(self, mol: Union[Mol, RWMol]):
         """
-        Generate an RDKitMol Molecule instance from a RDKit Chem.rdchem.Mol or RWMol molecule.
+        Generate an RDKitMol Molecule instance from a RDKit ``Chem.rdchem.Mol`` or ``RWMol`` molecule.
 
         Args:
-            mol (Union[Mol, RWMol]): The RDKit Chem.rdchem.Mol / RWmol molecule to be converted.
+            mol (Union[Mol, RWMol]): The RDKit ``Chem.rdchem.Mol`` / ``RWmol`` molecule to be converted.
         """
         # keep the link to original molecule so we can easily recover it if needed.
         if isinstance(mol, Mol):
@@ -84,14 +84,14 @@ def AlignMol(self,
 
         Args:
             refMol (Mol): RDKit molecule as a reference.
-            confid (int, optional): The conformer id to be aligned. Defaults to 0.
-            refCid (int, optional): The id of reference conformer. Defaults to 0.
+            confid (int, optional): The conformer id to be aligned. Defaults to ``0``.
+            refCid (int, optional): The id of reference conformer. Defaults to ``0``.
             reflect (bool, optional): Whether to reflect the conformation of the probe molecule.
-                                      Defaults to False.
-            atomMap (list, optional): a vector of pairs of atom IDs (probe AtomId, ref AtomId)
+                                      Defaults to ``False``.
+            atomMap (list, optional): a vector of pairs of atom IDs ``(probe AtomId, ref AtomId)``
                                       used to compute the alignments. If this mapping is not
                                       specified an attempt is made to generate on by substructure matching.
-            maxIters (int, optional): maximum number of iterations used in mimizing the RMSD. Defaults to 1000.
+            maxIters (int, optional): maximum number of iterations used in mimizing the RMSD. Defaults to ``1000``.
         """
         try:
             return Chem.rdMolAlign.AlignMol(prbMol=self._mol,
@@ -121,16 +121,16 @@ def Copy(self) -> 'RDKitMol':
 
     def EmbedConformer(self):
         """
-        Embed a conformer to the RDKitMol. This will overwrite current conformers.
+        Embed a conformer to the ``RDKitMol``. This will overwrite current conformers.
         """
         AllChem.EmbedMolecule(self._mol)
 
     def EmbedMultipleConfs(self, n: int = 1):
         """
-        Embed conformers to the RDKitMol. This will overwrite current conformers.
+        Embed conformers to the ``RDKitMol``. This will overwrite current conformers.
 
         Args:
-            n (int): The number of conformers to be embedded. The default is 1.
+            n (int): The number of conformers to be embedded. The default is ``1``.
         """
         AllChem.EmbedMultipleConfs(self._mol, numConfs=n)
 
@@ -142,13 +142,13 @@ def FromOBMol(cls,
                   embed: bool = True,
                   ) -> 'RDKitMol':
         """
-        Convert a OpenBabel molecular structure to an RDKit RDMol object.
+        Convert a OpenBabel Mol to an RDKitMol object.
 
         Args:
             ob_mol (Molecule): An OpenBabel Molecule object for the conversion.
-            remove_h (bool, optional): Whether to remove hydrogen atoms from the molecule, Defaults to False.
-            sanitize (bool, optional): Whether to sanitize the RDKit molecule. Defaults to True.
-            embed (bool, optional): Whether to embeb 3D conformer from OBMol. Defaults to True.
+            remove_h (bool, optional): Whether to remove hydrogen atoms from the molecule, Defaults to ``False``.
+            sanitize (bool, optional): Whether to sanitize the RDKit molecule. Defaults to ``True``.
+            embed (bool, optional): Whether to embeb 3D conformer from OBMol. Defaults to ``True``.
 
         Returns:
             RDKitMol: An RDKit molecule object corresponding to the input OpenBabel Molecule object.
@@ -161,10 +161,10 @@ def FromMol(cls,
                 mol: Union[Mol, RWMol],
                 ) -> 'RDKitMol':
         """
-        Convert a RDKit Chem.rdchem.Mol molecule to RDKitMol Molecule.
+        Convert a RDKit ``Chem.rdchem.Mol`` molecule to ``RDKitMol`` Molecule.
 
         Args:
-            rdmol (Union[Mol, RWMol]): The RDKit Chem.rdchem.Mol / RWMol molecule to be converted.
+            rdmol (Union[Mol, RWMol]): The RDKit ``Chem.rdchem.Mol`` / ``RWMol`` molecule to be converted.
 
         Returns:
             RDKitMol: An RDKitMol molecule.
@@ -178,7 +178,7 @@ def FromSmiles(cls,
                    sanitize: bool = True,
                    ) -> 'RDKitMol':
         """
-        Convert a smiles to an RDkit Mol object.
+        Convert a SMILES to an ``RDkitMol`` object.
 
         Args:
             smiles (str): A SMILES representation of the molecule.
@@ -202,10 +202,10 @@ def FromRMGMol(cls,
                    sanitize: bool = True,
                    ) -> 'RDKitMol':
         """
-        Convert an RMG Molecule to an RDkit Mol object.
+        Convert an RMG ``Molecule`` to an ``RDkitMol`` object.
 
         Args:
-            smiles (str): An RMG Molecule instance.
+            smiles (str): An RMG ``Molecule`` instance.
             remove_h (bool, optional): Whether to remove hydrogen atoms from the molecule, ``True`` to remove.
             sanitize (bool, optional): Whether to sanitize the RDKit molecule, ``True`` to sanitize.
 
@@ -227,16 +227,17 @@ def FromXYZ(cls,
 
         Args:
             xyz (str): A XYZ String.
-            backend (str): The backend used to perceive molecule. Defaults to "pybel".
-                           Currently, we only support "pybel" and "jensen".
+            backend (str): The backend used to perceive molecule. Defaults to ``pybel``.
+                           Currently, we only support ``pybel`` and ``jensen``.
             header (bool, optional): If lines of the number of atoms and title are included.
-                                     Defaults to True.
+                                     Defaults to ``True.``
             supported kwargs:
-                jensen: - charge: The charge of the species. Defaults to 0.
-                        - allow_charged_fragments: ``True`` for charged fragment, ``False`` for radical. Defaults to False.
-                        - use_graph: ``True`` to use networkx module for accelerate. Defaults to True.
-                        - use_huckel: ``True`` to use extended Huckel bond orders to locate bonds. Defaults to False.
-                        - embed_chiral: ``True`` to embed chiral information. Defaults to True.
+                jensen:
+                    - charge: The charge of the species. Defaults to ``0``.
+                    - allow_charged_fragments: ``True`` for charged fragment, ``False`` for radical. Defaults to False.
+                    - use_graph: ``True`` to use networkx module for accelerate. Defaults to True.
+                    - use_huckel: ``True`` to use extended Huckel bond orders to locate bonds. Defaults to False.
+                    - embed_chiral: ``True`` to embed chiral information. Defaults to True.
 
         Returns:
             RDKitMol: An RDKit molecule object corresponding to the xyz.
@@ -292,15 +293,10 @@ def GetElementSymbols(self):
     def GetConformer(self,
                      id: int = 0) -> 'RDKitConf':
         """
-        Get the embedded conformer according to ID. The relationship:
-                       mol
-            RDKitMol ======== RWMol
-           owing ||           || owing
-             mol ||           || mol
-            RDKitConf ====== Conformer
-                     conformer
+        Get the embedded conformer according to ID.
+
         Args:
-            id (int): The ID of the conformer to be obtained. The default is 0.
+            id (int): The ID of the conformer to be obtained. The default is ``0``.
 
         Raises:
             ValueError: Bad id assigned.
@@ -324,7 +320,7 @@ def GetConformers(self,
 
         Args:
             ids (Union[list, tuple]): The ids of the conformer to be obtained.
-                                      The default is [0].
+                                      The default is ``[0]``.
 
         Raises:
             ValueError: Bad id assigned.
@@ -363,9 +359,9 @@ def GetSubstructMatch(self,
         Returns the indices of the molecule's atoms that match a substructure query.
 
         Args:
-            query (Mol): a Molecule.
-            useChirality (bool, optional): enables the use of stereochemistry in the matching. Defaults to False.
-            useQueryQueryMatches (bool, optional): use query-query matching logic. Defaults to False.
+            query (Mol): a RDkit Molecule.
+            useChirality (bool, optional): enables the use of stereochemistry in the matching. Defaults to ``False``.
+            useQueryQueryMatches (bool, optional): use query-query matching logic. Defaults to ``False``.
 
         Returns:
             tuple: A tuple of matched indices.
@@ -409,7 +405,7 @@ def GetTorsionalModes(self,
         Get all of the torsional modes (rotors) from the molecule.
 
         Args:
-            exclude_methyl (bool): Whether exclude the torsions with methyl groups.
+            exclude_methyl (bool): Whether exclude the torsions with methyl groups. Defaults to ``False``.
 
         Returns:
             list: A list of four-atom-indice to indicating the torsional modes.
@@ -426,15 +422,17 @@ def PrepareOutputMol(self,
 
         Args:
             remove_h (bool, optional): Remove less useful explicity H atoms. E.g., When output SMILES, H atoms,
-                      if explicitly added, will be included and reduce the readablity. Note, following Hs are not removed:
-                        1. H which aren’t connected to a heavy atom. E.g.,[H][H].
-                        2. Labelled H. E.g., atoms with atomic number=1, but isotope > 1.
-                        3. Two coordinate Hs. E.g., central H in C[H-]C.
-                        4. Hs connected to dummy atoms
-                        5. Hs that are part of the definition of double bond Stereochemistry.
-                        6. Hs that are not connected to anything else.
-                        Defaults to False:
-            sanitize (bool, optional): whether to sanitize the molecule. Defaults to True.
+                if explicitly added, will be included and reduce the readablity. Defaults to ``False``.
+                Note, following Hs are not removed:
+
+                    1. H which aren’t connected to a heavy atom. E.g.,[H][H].
+                    2. Labelled H. E.g., atoms with atomic number=1, but isotope > 1.
+                    3. Two coordinate Hs. E.g., central H in C[H-]C.
+                    4. Hs connected to dummy atoms
+                    5. Hs that are part of the definition of double bond Stereochemistry.
+                    6. Hs that are not connected to anything else.
+
+            sanitize (bool, optional): whether to sanitize the molecule. Defaults to ``True``.
 
         Returns:
             Mol: A Mol instance used for output purpose.
@@ -453,8 +451,8 @@ def RenumberAtoms(self,
 
         Args:
             newOrder (list): the new ordering the atoms (should be numAtoms long). E.g,
-                             if newOrder is [3,2,0,1], then atom 3 in the original molecule
-                             will be atom 0 in the new one.
+                if newOrder is [3,2,0,1], then atom 3 in the original molecule
+                will be atom 0 in the new one.
 
         Returns:
             RDKitMol: Molecule with reordered atoms.
@@ -512,11 +510,11 @@ def ToSmiles(self,
         Convert RDKitMol to a SMILES string.
 
         Args:
-            stereo (bool, optional): Whether keep stereochemistry information. Defaults to True.
-            kekule (bool, optional): Whether use Kekule form. Defaults to False.
-            canonical (bool, optional): Whether generate a canonical SMILES. Defaults to True.
-            mapid (bool, optional): Whether to keep map id information in the SMILES. Defaults to False.
-            remove_h (bool, optional): Whether to remove H atoms to make obtained SMILES clean. Defaults to True.
+            stereo (bool, optional): Whether keep stereochemistry information. Defaults to ``True``.
+            kekule (bool, optional): Whether use Kekule form. Defaults to ``False``.
+            canonical (bool, optional): Whether generate a canonical SMILES. Defaults to ``True``.
+            mapid (bool, optional): Whether to keep map id information in the SMILES. Defaults to ``False``.
+            remove_h (bool, optional): Whether to remove H atoms to make obtained SMILES clean. Defaults to ``True``.
 
         Returns:
             str: The smiles string of the molecule.
@@ -543,9 +541,9 @@ def ToXYZ(self,
         Args:
             conf_id (int): The conformer ID to be exported.
             header (bool, optional): Whether to include header (first two lines).
-                                     Defaults to True.
+                                     Defaults to ``True``.
 
-        Returns
+        Returns:
             str: The xyz of the molecule.
         """
         xyz = Chem.MolToXYZBlock(self._mol, conf_id)
@@ -575,7 +573,7 @@ def EmbedMultipleConfs(self, n: int = 1):
         All coordinates will be initialized to zeros.
 
         Args:
-            n (int): The number of conformers to be embedded. Defaults to 1.
+            n (int): The number of conformers to be embedded. Defaults to ``1``.
         """
         self._mol.RemoveAllConformers()
         num_atoms = self._mol.GetNumAtoms()