Merge pull request #299 from umesh-timalsina/284-docstrings

Docathon Assignments

docs/conf.py

@@ -45,8 +45,9 @@
 napoleon_numpy_docstring = True
 napoleon_use_admonition_for_notes = True
 napoleon_use_param = False
+napoleon_use_ivar = True
 
-
+intersphinx_mapping = {'python': ('https://docs.python.org/3.7', None)}
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

docs/data_structures.rst

@@ -1,9 +1,19 @@
 Data Structures in GMSO 
 ---------------------------
-Following data structures are available within GMSO, which are generally referred to  `CoreMembers` and `CoreTypes`.
+Following data structures are available within GMSO.
 
-Core Members
-=============
+Core Classes
+============
+
+Topology
+********
+    .. autoclass:: gmso.Topology
+        :members: add_site, add_bond, add_angle
+
+SubTopology
+***********
+    .. autoclass:: gmso.SubTopology
+        :members:
 
 Site
 ****
@@ -25,8 +35,9 @@ Dihedral
     .. autoclass:: gmso.Dihedral
         :members:
 
-Potential Classes(CoreTypes)
-============================
+
+Potential Classes
+=================
     .. autoclass:: gmso.Potential
         :members:
 
@@ -51,3 +62,7 @@ DihedralType
         :members:
 
 
+ForceField
+==========
+    .. autoclass:: gmso.ForceField
+        :members:

docs/index.rst

@@ -15,7 +15,6 @@ Design Framework.
 
    design_principles
    data_structures
-   forcefield
    formats
    external
    installation

gmso/core/forcefield.py

@@ -9,32 +9,43 @@
 class ForceField(object):
     """A generic implementation of the forcefield class.
 
-    A forcefield class contains different collection of
-    core type members.
+    The ForceField class is one of the core data structures in gmso, which is
+    used to hold a collection of gmso.core.Potential subclass objects along with some
+    metadata to represent a forcefield. The forcefield object can be applied
+    to any gmso.Topology which has effects on its Sites, Bonds, Angles and Dihedrals.
 
     Parameters
     ----------
-    name: (str), Name of the forcefield, default 'ForceField'
-    version: (str), a cannonical semantic version of the forcefield, default 1.0.0
+    name : str
+        Name of the forcefield, default 'ForceField'
+    version : str
+        a cannonical semantic version of the forcefield, default 1.0.0
 
     Attributes
-    -----------
-    name: (str), Name of the forcefield
-    version: (str), Version of the forcefield
-    atom_types: (dict), A collection of atom types in the forcefield
-    bond_types: (dict), A collection of bond types in the forcefield
-    angle_types: (dict), A collection of angle types in the forcefield
-    dihedral_types: (dict), A collection of dihedral types in the forcefield
+    ----------
+    name : str
+        Name of the forcefield
+    version : str
+        Version of the forcefield
+    atom_types : dict
+        A collection of atom types in the forcefield
+    bond_types : dict
+        A collection of bond types in the forcefield
+    angle_types : dict
+        A collection of angle types in the forcefield
+    dihedral_types : dict
+        A collection of dihedral types in the forcefield
+    units : dict
+        A collection of unyt.Unit objects used in the forcefield
+    scaling_factors : dict
+        A collection of scaling factors used in the forcefield
+
+    See Also
+    --------
+    gmso.ForceField.from_xml : A class method to create forcefield object from XML files
+
     """
     def __init__(self, xml_loc=None):
-        """Initialize a new ForceField
-
-        Parameters
-        ----------
-        name: str, name of the forcefield, default 'ForceField', usage optional
-        version: str, version of the forcefield, default 'ForceField', usage optional
-        xml_locs: iterable, list of GMSO's Forcefield XML Files, default None, usage optional
-        """
         if xml_loc is not None:
             ff = ForceField.from_xml(xml_loc)
             self.name = ff.name
@@ -79,16 +90,23 @@ def atom_class_groups(self):
 
     @classmethod
     def from_xml(cls, xml_locs):
-        """Create a forcefield object from a XML File
-        Parameters:
-        -----------
-        xml_locs: (str) or iter(str), string or iterable of strings
-                  containing the forcefield XML locations
+        """Create a gmso.Forcefield object from XML File(s)
+
+        This class method creates a ForceFiled object from the reference
+        XML file. This method takes in a single or collection of XML files
+        with information about gmso.AtomTypes, gmso.BondTypes, gmso.AngleTypes
+        and gmso.DihedralTypes to create the ForceField object.
+
+        Parameters
+        ----------
+        xml_locs : str or iterable of str
+            string or iterable of strings containing the forcefield XML locations
 
-        Returns:
+        Returns
         --------
-        gmso.forcefield.ForceField object, containing all the information
-            from the ForceField File
+        forcefield : gmso.ForceField
+            A gmso.Forcefield object with a collection of Potential objects
+            created using the information in the XML file
         """
 
         if not hasattr(xml_locs, '__iter__'):

gmso/core/potential.py

@@ -140,7 +140,7 @@ def set_expression(self, expression=None, parameters=None, independent_variables
         Be aware of the symbols used in the `expression` and `parameters`.
         If unnecessary parameters are supplied, an error is thrown.
         If only a subset of the parameters are supplied, they are updated
-            while the non-passed parameters default to the existing values
+        while the non-passed parameters default to the existing values
        """
         if expression is not None:
             self._expression = _validate_expression(expression)

gmso/core/subtopology.py

@@ -7,7 +7,28 @@
 
 
 class SubTopology(object):
-    """A sub-topology."""
+    """A sub-topology i.e. topology within a topology
+
+    This class provides a hierarchical topological representation to
+    the topology as it imperative with many chemical structures to have
+    separation of layers/ boundaries. A sub-topology can be added to a
+    gmso.Topology object which will be the parent of the sub-topology.
+
+    Parameters
+    ----------
+    name : str, optional, default='Sub-Topology'
+        Name of the sub-topology
+    parent : gmso.Topology, optional, default=None
+        The parent topology of this SubTopology
+
+    Attributes
+    ----------
+    sites : IndexedSet of gmso.Site objects
+        Collection of sites within this sub-topology
+    n_sites : int
+        Number of sites withing this sub-topology
+    """
+
     def __init__(self, name="Sub-Topology", parent=None):
         if name is not None:
             self._name = str(name)
@@ -50,6 +71,23 @@ def parent(self, parent):
         self._parent = _validate_parent(parent)
 
     def add_site(self, site):
+        """Add a site to this sub-topology
+
+        This method adds a site to the sub-topology.
+        If the sub-topology has a parent, the site will
+        also be added to the parent topology.
+
+        Parameters
+        ----------
+        site : gmso.Site
+            The site to be added to this sub-topology
+
+        Raises
+        ------
+        TypeError
+            If the parameter site is not of type topology.Site
+        """
+
         site = _validate_site_addability(site)
         if site in self.sites:
             warnings.warn("Redundantly adding Site {}".format(site))