Improve docstrings

Swigged python docstrings now include documented return values and type
information or their arguments. They are generated in numpydoc format.
Furthermore, all of the Python app layer docstrings have been changed
to numpydoc format. The filterPythonFiles.py script which helps to
generate the Doxygen Python API docs has been updated to reflect these
changes.

wrappers/python/simtk/openmm/app/charmmpsffile.py

@@ -116,11 +116,7 @@ def _strip_optunit(thing, unit):
 _resre = re.compile(r'(\d+)([a-zA-Z]*)')
 
 class CharmmPsfFile(object):
-    """
-    A chemical structure instantiated from CHARMM files.
-
-    Example:
-    >>> cs = CharmmPsfFile("testfiles/test.psf")
+    """A chemical structure instantiated from CHARMM files.
 
     This structure has numerous attributes that are lists of the elements of
     this structure, including atoms, bonds, torsions, etc. The attributes are
@@ -144,7 +140,8 @@ class CharmmPsfFile(object):
     The lengths of each of these lists gives the pointers (e.g., natom, nres,
     etc.)
 
-    Example:
+    Examples
+    --------
     >>> cs = CharmmPsfFile("testfiles/test.psf")
     >>> len(cs.atom_list)
     33
@@ -166,14 +163,16 @@ class CharmmPsfFile(object):
 
     @_catchindexerror
     def __init__(self, psf_name):
-        """
-        Opens and parses a PSF file, then instantiates a CharmmPsfFile
+        """Opens and parses a PSF file, then instantiates a CharmmPsfFile
         instance from the data.
 
-        Parameters:
-            psf_name (str) : Name of the PSF file (it must exist)
+        Parameters
+        ----------
+        psf_name : str
+            Name of the PSF file (it must exist)
 
-        Exceptions Raised:
+        Raises
+        ------
         IOError : If file "psf_name" does not exist
         CharmmPSFError: If any parsing errors are encountered
         """
@@ -388,14 +387,17 @@ class CharmmPsfFile(object):
 
     @staticmethod
     def _convert(string, type, message):
-        """
-        Converts a string to a specific type, making sure to raise
+        """Converts a string to a specific type, making sure to raise
         CharmmPSFError with the given message in the event of a failure.
 
-        Parameters:
-            - string (str) : Input string to process
-            - type (type) : Type of data to convert to
-            - message (str) : Error message to put in exception if failed
+        Parameters
+        ----------
+        string : str
+            Input string to process
+        type : type
+            Type of data to convert to
+        message : str
+            Error message to put in exception if failed
         """
         try:
             return type(string)
@@ -405,23 +407,24 @@ class CharmmPsfFile(object):
 
     @staticmethod
     def _parse_psf_section(psf):
-        """
-        This method parses a section of the PSF file
-
-        Parameters:
-            - psf (CharmmFile) : Open file that is pointing to the first line
-                                 of the section that is to be parsed
-        
-        Returns:
-            (title, pointers, data)
-
-            - title (str) : The label of the PSF section we are parsing
-            - pointers (int/tuple of ints) : If one pointer is set, pointers is
-                    simply the integer that is value of that pointer. Otherwise
-                    it is a tuple with every pointer value defined in the first
-                    line
-            - data (list) : A list of all data in the parsed section converted
-                    to `dtype'
+        """This method parses a section of the PSF file
+
+        Parameters
+        ----------
+         psf : CharmmFile
+             Open file that is pointing to the first line of the section
+             that is to be parsed
+
+        Returns
+        --------
+        title : str
+            The label of the PSF section we are parsing
+        pointers : int/tuple of ints
+            If one pointer is set, pointers is simply the integer that is
+            value of that pointer. Otherwise it is a tuple with every pointer
+            value defined in the first line
+        data : list
+            A list of all data in the parsed section converted to `dtype'
         """
         conv = CharmmPsfFile._convert
         line = psf.readline()
@@ -462,22 +465,22 @@ class CharmmPsfFile(object):
         return title, pointers, data
 
     def loadParameters(self, parmset):
-        """
-        Loads parameters from a parameter set that was loaded via CHARMM RTF,
+        """Loads parameters from a parameter set that was loaded via CHARMM RTF,
         PAR, and STR files.
 
-        Parameters:
-            - parmset (CharmmParameterSet) : List of all parameters
+        Parameters
+        ----------
+        parmset : CharmmParameterSet
+            List of all parameters
 
-        Notes:
+        Notes
+        -----
         - If any parameters that are necessary cannot be found, a
           MissingParameter exception is raised.
-
         - If any dihedral or improper parameters cannot be found, I will try
           inserting wildcards (at either end for dihedrals and as the two
           central atoms in impropers) and see if that matches.  Wild-cards
           will apply ONLY if specific parameters cannot be found.
-
         - This method will expand the dihedral_parameter_list attribute by
           adding a separate Dihedral object for each term for types that
           have a multi-term expansion
@@ -752,52 +755,60 @@ class CharmmPsfFile(object):
                      ewaldErrorTolerance=0.0005,
                      flexibleConstraints=True,
                      verbose=False):
-        """
-        Construct an OpenMM System representing the topology described by the
+        """Construct an OpenMM System representing the topology described by the
         prmtop file. You MUST have loaded a parameter set into this PSF before
         calling createSystem. If not, AttributeError will be raised. ValueError
         is raised for illegal input.
 
-        Parameters:
-         -  params (CharmmParameterSet) The parameter set to use to parametrize
-               this molecule
-         -  nonbondedMethod (object=NoCutoff) The method to use for nonbonded
-               interactions. Allowed values are NoCutoff, CutoffNonPeriodic,
-               CutoffPeriodic, Ewald, or PME.
-         -  nonbondedCutoff (distance=1*nanometer) The cutoff distance to use
-               for nonbonded interactions.
-         -  switchDistance (distance=0*nanometer) The distance at which the
-               switching function is active for nonbonded interactions. If the
-               switchDistance evaluates to boolean False (if it is 0), no
-               switching function will be used. Illegal values will raise a
-               ValueError
-         -  constraints (object=None) Specifies which bonds or angles should be
-               implemented with constraints. Allowed values are None, HBonds,
-               AllBonds, or HAngles.
-         -  rigidWater (boolean=True) If true, water molecules will be fully
-               rigid regardless of the value passed for the constraints argument
-         -  implicitSolvent (object=None) If not None, the implicit solvent
-               model to use. Allowed values are HCT, OBC1, OBC2, or GBn
-         -  implicitSolventKappa (float=None): Debye screening parameter to
-               model salt concentrations in GB solvent.
-         -  implicitSolventSaltConc (float=0.0*u.moles/u.liter): Salt
-               concentration for GB simulations. Converted to Debye length
+        Parameters
+        ----------
+        params : CharmmParameterSet
+            The parameter set to use to parametrize this molecule
+        nonbondedMethod : object=NoCutoff
+            The method to use for nonbonded interactions. Allowed values are
+            NoCutoff, CutoffNonPeriodic, CutoffPeriodic, Ewald, or PME.
+        nonbondedCutoff : distance=1*nanometer
+            The cutoff distance to use for nonbonded interactions.
+        switchDistance : distance=0*nanometer
+            The distance at which the switching function is active for nonbonded
+            interactions. If the switchDistance evaluates to boolean False (if
+            it is 0), no switching function will be used. Illegal values will
+            raise a ValueError
+        constraints : object=None
+            Specifies which bonds or angles should be implemented with
+            constraints. Allowed values are None, HBonds, AllBonds, or HAngles.
+        rigidWater : boolean=True
+            If true, water molecules will be fully rigid regardless of the value
+            passed for the constraints argument
+        implicitSolvent : object=None
+            If not None, the implicit solvent model to use. Allowed values are
+            HCT, OBC1, OBC2, or GBn
+        implicitSolventKappa : float=None
+            Debye screening parameter to model salt concentrations in GB
+            solvent.
+        implicitSolventSaltConc : float=0.0*u.moles/u.liter
+            Salt concentration for GB simulations. Converted to Debye length
             `kappa'
-         -  temperature (float=298.15*u.kelvin): Temperature used in the salt
-               concentration-to-kappa conversion for GB salt concentration term
-         -  soluteDielectric (float=1.0) The solute dielectric constant to use
-               in the implicit solvent model.
-         -  solventDielectric (float=78.5) The solvent dielectric constant to
-               use in the implicit solvent model.
-         -  removeCMMotion (boolean=True) If true, a CMMotionRemover will be
-               added to the System.
-         -  hydrogenMass (mass=None) The mass to use for hydrogen atoms bound to
-               heavy atoms. Any mass added to a hydrogen is subtracted from the
-               heavy atom to keep their total mass the same.
-         -  ewaldErrorTolerance (float=0.0005) The error tolerance to use if the
-               nonbonded method is Ewald or PME.
-         -  flexibleConstraints (bool=True) Are our constraints flexible or not?
-         -  verbose (bool=False) Optionally prints out a running progress report
+        temperature : float=298.15*u.kelvin
+            Temperature used in the salt concentration-to-kappa conversion for
+            GB salt concentration term
+        soluteDielectric : float=1.0
+            The solute dielectric constant to use in the implicit solvent model.
+        solventDielectric : float=78.5
+            The solvent dielectric constant to use in the implicit solvent
+            model.
+        removeCMMotion : boolean=True
+            If true, a CMMotionRemover will be added to the System.
+        hydrogenMass : mass=None
+            The mass to use for hydrogen atoms bound to heavy atoms. Any mass
+            added to a hydrogen is subtracted from the heavy atom to keep their
+            total mass the same.
+        ewaldErrorTolerance : float=0.0005
+            The error tolerance to use if the nonbonded method is Ewald or PME.
+        flexibleConstraints : bool=True
+            Are our constraints flexible or not?
+        verbose : bool=False
+            Optionally prints out a running progress report
         """
         # Load the parameter set
         self.loadParameters(params.condense())

wrappers/python/simtk/openmm/app/checkpointreporter.py

@@ -71,10 +71,12 @@ class CheckpointReporter(object):
     def __init__(self, file, reportInterval):
         """Create a CheckpointReporter.
 
-        Parameters:
-         - file (string or open file object) The file to write to. Any current
-           contents will be overwritten.
-         - reportInterval (int) The interval (in time steps) at which to write checkpoints
+        Parameters
+        ----------
+        file : string or open file object
+            The file to write to. Any current contents will be overwritten.
+        reportInterval : int
+            The interval (in time steps) at which to write checkpoints.
         """
 
         self._reportInterval = reportInterval
@@ -88,12 +90,23 @@ class CheckpointReporter(object):
     def describeNextReport(self, simulation):
         """Get information about the next report this object will generate.
 
-        Parameters:
-         - simulation (Simulation) The Simulation to generate a report for
-
-        Returns: A five element tuple.  The first element is the number of steps until the
-        next report.  The remaining elements specify whether that report will require
-        positions, velocities, forces, and energies respectively.
+        Parameters
+        ----------
+        simulation : Simulation
+            The Simulation to generate a report for
+
+        Returns
+        -------
+        int
+            The number of steps until the
+        bool
+            Requires positions
+        bool
+            Requires velocities
+        bool
+            Requires forces
+        bool
+            Requires energies
         """
         steps = self._reportInterval - simulation.currentStep%self._reportInterval
         return (steps, False, False, False, False)
@@ -101,9 +114,12 @@ class CheckpointReporter(object):
     def report(self, simulation, state):
         """Generate a report.
 
-        Parameters:
-         - simulation (Simulation) The Simulation to generate a report for
-         - state (State) The current state of the simulation
+        Parameters
+        ----------
+        simulation : Simulation
+            The Simulation to generate a report for
+        state : State
+            The current state of the simulation
         """
         self._out.seek(0)
         chk = simulation.context.createCheckpoint()

wrappers/python/simtk/openmm/app/dcdfile.py

@@ -55,12 +55,19 @@ class DCDFile(object):
     def __init__(self, file, topology, dt, firstStep=0, interval=1):
         """Create a DCD file and write out the header.
 
-        Parameters:
-         - file (file) A file to write to
-         - topology (Topology) The Topology defining the molecular system being written
-         - dt (time) The time step used in the trajectory
-         - firstStep (int=0) The index of the first step in the trajectory
-         - interval (int=1) The frequency (measured in time steps) at which states are written to the trajectory
+        Parameters
+        ----------
+        file : file
+            A file to write to
+        topology : Topology
+            The Topology defining the molecular system being written
+        dt : time
+            The time step used in the trajectory
+        firstStep : int=0
+            The index of the first step in the trajectory
+        interval : int=1
+            The frequency (measured in time steps) at which states are written
+            to the trajectory
         """
         self._file = file
         self._topology = topology
@@ -83,14 +90,21 @@ class DCDFile(object):
     def writeModel(self, positions, unitCellDimensions=None, periodicBoxVectors=None):
         """Write out a model to the DCD file.
 
-        The periodic box can be specified either by the unit cell dimensions (for a rectangular box), or the full set of box
-        vectors (for an arbitrary triclinic box).  If neither is specified, the box vectors specified in the Topology will be
-        used.  Regardless of the value specified, no dimensions will be written if the Topology does not represent a periodic system.
-
-        Parameters:
-         - positions (list) The list of atomic positions to write
-         - unitCellDimensions (Vec3=None) The dimensions of the crystallographic unit cell.
-         - periodicBoxVectors (tuple of Vec3=None) The vectors defining the periodic box.
+        The periodic box can be specified either by the unit cell dimensions
+        (for a rectangular box), or the full set of box vectors (for an
+        arbitrary triclinic box).  If neither is specified, the box vectors
+        specified in the Topology will be used. Regardless of the value
+        specified, no dimensions will be written if the Topology does not
+        represent a periodic system.
+
+        Parameters
+        ----------
+        positions : list
+            The list of atomic positions to write
+        unitCellDimensions : Vec3=None
+            The dimensions of the crystallographic unit cell.
+        periodicBoxVectors : tuple of Vec3=None
+            The vectors defining the periodic box.
         """
         if len(list(self._topology.atoms())) != len(positions):
             raise ValueError('The number of positions must match the number of atoms')

wrappers/python/simtk/openmm/app/dcdreporter.py

@@ -56,11 +56,23 @@ class DCDReporter(object):
     def describeNextReport(self, simulation):
         """Get information about the next report this object will generate.
 
-        Parameters:
-         - simulation (Simulation) The Simulation to generate a report for
-        Returns: A five element tuple.  The first element is the number of steps until the
-        next report.  The remaining elements specify whether that report will require
-        positions, velocities, forces, and energies respectively.
+        Parameters
+        ----------
+        simulation : Simulation
+            The Simulation to generate a report for
+
+        Returns
+        -------
+        int
+            The number of steps until the
+        bool
+            Requires positions
+        bool
+            Requires velocities
+        bool
+            Requires forces
+        bool
+            Requires energies
         """
         steps = self._reportInterval - simulation.currentStep%self._reportInterval
         return (steps, True, False, False, False)
@@ -68,10 +80,14 @@ class DCDReporter(object):
     def report(self, simulation, state):
         """Generate a report.
 
-        Parameters:
-         - simulation (Simulation) The Simulation to generate a report for
-         - state (State) The current state of the simulation
+        Parameters
+        ----------
+        simulation : Simulation
+            The Simulation to generate a report for
+        state : State
+            The current state of the simulation
         """
+
         if self._dcd is None:
             self._dcd = DCDFile(self._out, simulation.topology, simulation.integrator.getStepSize(), 0, self._reportInterval)
         a,b,c = state.getPeriodicBoxVectors()

wrappers/python/simtk/openmm/app/desmonddmsfile.py

@@ -157,16 +157,24 @@ class DesmondDMSFile(object):
 
     def createSystem(self, nonbondedMethod=ff.NoCutoff, nonbondedCutoff=1.0*nanometer,
                      ewaldErrorTolerance=0.0005, removeCMMotion=True, hydrogenMass=None):
-        """Construct an OpenMM System representing the topology described by this dms file
+        """Construct an OpenMM System representing the topology described by this
+        DMS file
 
-        Parameters:
-         - nonbondedMethod (object=NoCutoff) The method to use for nonbonded interactions.  Allowed values are
+        Parameters
+        ----------
+        nonbondedMethod : object=NoCutoff
+            The method to use for nonbonded interactions.  Allowed values are
             NoCutoff, CutoffNonPeriodic, CutoffPeriodic, Ewald, or PME.
-         - nonbondedCutoff (distance=1*nanometer) The cutoff distance to use for nonbonded interactions
-         - ewaldErrorTolerance (float=0.0005) The error tolerance to use if nonbondedMethod is Ewald or PME.
-         - removeCMMotion (boolean=True) If true, a CMMotionRemover will be added to the System
-         - hydrogenMass (mass=None) The mass to use for hydrogen atoms bound to heavy atoms.  Any mass added to a hydrogen is
-           subtracted from the heavy atom to keep their total mass the same.
+        nonbondedCutoff : distance=1*nanometer
+            The cutoff distance to use for nonbonded interactions
+        ewaldErrorTolerance : float=0.0005
+            The error tolerance to use if nonbondedMethod is Ewald or PME.
+        removeCMMotion : boolean=True
+            If true, a CMMotionRemover will be added to the System
+        hydrogenMass : mass=None
+            The mass to use for hydrogen atoms bound to heavy atoms.  Any mass
+            added to a hydrogen is subtracted from the heavy atom to keep their
+            total mass the same.
         """
         self._checkForUnsupportedTerms()
         sys = mm.System()

wrappers/python/simtk/openmm/app/forcefield.py

@@ -123,12 +123,14 @@ class ForceField(object):
     def loadFile(self, file):
         """Load an XML file and add the definitions from it to this FieldField.
 
-        Parameters:
-         - file (string or file) An XML file containing force field definitions.  It may
-           be either an absolute file path, a path relative to the current working
-           directory, a path relative to this module's data subdirectory
-           (for built in force fields), or an open file-like object with a
-           read() method from which the forcefield XML data can be loaded.
+        Parameters
+        ----------
+        file : string or file
+            An XML file containing force field definitions.  It may be either an
+            absolute file path, a path relative to the current working
+            directory, a path relative to this module's data subdirectory (for
+            built in force fields), or an open file-like object with a read()
+            method from which the forcefield XML data can be loaded.
         """
         try:
             # this handles either filenames or open file-like objects

wrappers/python/simtk/openmm/app/gromacsgrofile.py

@@ -183,9 +183,13 @@ class GromacsGroFile(object):
     def getPositions(self, asNumpy=False, frame=0):
         """Get the atomic positions.
 
-        Parameters:
-         - asNumpy (boolean=False) if true, the values are returned as a numpy array instead of a list of Vec3s
-         - frame (int=0) the index of the frame for which to get positions
+        Parameters
+        ----------
+        asNumpy : boolean=False
+            if true, the values are returned as a numpy array instead of a list
+            of Vec3s
+        frame : int=0
+            the index of the frame for which to get positions
         """
         if asNumpy:
             if self._numpyPositions is None:
@@ -198,16 +202,20 @@ class GromacsGroFile(object):
     def getPeriodicBoxVectors(self, frame=0):
         """Get the vectors defining the periodic box.
 
-        Parameters:
-         - frame (int=0) the index of the frame for which to get the box vectors
+        Parameters
+        ----------
+        frame : int=0
+            the index of the frame for which to get the box vectors
         """
         return self._periodicBoxVectors[frame]
 
     def getUnitCellDimensions(self, frame=0):
         """Get the dimensions of the crystallographic unit cell.
 
-        Parameters:
-         - frame (int=0) the index of the frame for which to get the unit cell dimensions
+        Parameters
+        ----------
+        frame : int=0
+            the index of the frame for which to get the unit cell dimensions
         """
         xsize = self._periodicBoxVectors[frame][0][0].value_in_unit(nanometers)
         ysize = self._periodicBoxVectors[frame][1][1].value_in_unit(nanometers)

wrappers/python/simtk/openmm/app/gromacstopfile.py

@@ -539,23 +539,42 @@ class GromacsTopFile(object):
 
     def createSystem(self, nonbondedMethod=ff.NoCutoff, nonbondedCutoff=1.0*unit.nanometer,
                      constraints=None, rigidWater=True, implicitSolvent=None, soluteDielectric=1.0, solventDielectric=78.5, ewaldErrorTolerance=0.0005, removeCMMotion=True, hydrogenMass=None):
-        """Construct an OpenMM System representing the topology described by this prmtop file.
+        """Construct an OpenMM System representing the topology described by this
+        prmtop file.
 
-        Parameters:
-         - nonbondedMethod (object=NoCutoff) The method to use for nonbonded interactions.  Allowed values are
+        Parameters
+        ----------
+        nonbondedMethod : object=NoCutoff
+            The method to use for nonbonded interactions.  Allowed values are
             NoCutoff, CutoffNonPeriodic, CutoffPeriodic, Ewald, or PME.
-         - nonbondedCutoff (distance=1*nanometer) The cutoff distance to use for nonbonded interactions
-         - constraints (object=None) Specifies which bonds and angles should be implemented with constraints.
-           Allowed values are None, HBonds, AllBonds, or HAngles.
-         - rigidWater (boolean=True) If true, water molecules will be fully rigid regardless of the value passed for the constraints argument
-         - implicitSolvent (object=None) If not None, the implicit solvent model to use.  The only allowed value is OBC2.
-         - soluteDielectric (float=1.0) The solute dielectric constant to use in the implicit solvent model.
-         - solventDielectric (float=78.5) The solvent dielectric constant to use in the implicit solvent model.
-         - ewaldErrorTolerance (float=0.0005) The error tolerance to use if nonbondedMethod is Ewald or PME.
-         - removeCMMotion (boolean=True) If true, a CMMotionRemover will be added to the System
-         - hydrogenMass (mass=None) The mass to use for hydrogen atoms bound to heavy atoms.  Any mass added to a hydrogen is
-           subtracted from the heavy atom to keep their total mass the same.
-        Returns: the newly created System
+        nonbondedCutoff : distance=1*nanometer
+            The cutoff distance to use for nonbonded interactions
+        constraints : object=None
+            Specifies which bonds and angles should be implemented with
+            constraints. Allowed values are None, HBonds, AllBonds, or HAngles.
+        rigidWater : boolean=True
+            If true, water molecules will be fully rigid regardless of the value
+            passed for the constraints argument
+        implicitSolvent : object=None
+            If not None, the implicit solvent model to use.  The only allowed
+            value is OBC2.
+        soluteDielectric : float=1.0
+            The solute dielectric constant to use in the implicit solvent model.
+        solventDielectric : float=78.5
+            The solvent dielectric constant to use in the implicit solvent
+            model.
+        ewaldErrorTolerance : float=0.0005
+            The error tolerance to use if nonbondedMethod is Ewald or PME.
+        removeCMMotion : boolean=True
+            If true, a CMMotionRemover will be added to the System
+        hydrogenMass : mass=None
+            The mass to use for hydrogen atoms bound to heavy atoms.  Any mass
+            added to a hydrogen is subtracted from the heavy atom to keep their
+            total mass the same.
+
+        Returns
+        -------
+             the newly created System
         """
         # Create the System.
 

wrappers/python/simtk/openmm/app/internal/charmm/topologyobjects.py

@@ -76,22 +76,33 @@ class AtomType(object):
     new atom types with the "add" constructor to make sure the registry is
     filled with only unique types
 
-    Parameters and Attributes:
-        - name (str) : The name of the atom type
-        - number (int) : The integer index of the atom type
-        - mass (float) : The mass of the atom type
-        - atomic_number (int) : The atomic number of the element of the atom
-                                type
-    Attributes:
-        - name (str) : The name of the atom type
-        - number (int) : The integer index of the atom type
-        - _member_number (int, private) : The order in which this atom type
-                was 'added' this is used to make sure that atom types added
-                last have priority in assignment in the generated hash tables
-        - nbfix (dict) : Dictionary that maps nbfix terms with other atom types.
-                         Dict entries are (rmin, epsilon) -- precombined values
-                         for that particular atom pair
-    Example:
+    Parameters
+    ----------
+    name : str
+        The name of the atom type
+    number : int
+        The integer index of the atom type
+    mass : float
+        The mass of the atom type
+    atomic_number : int
+        The atomic number of the element of the atom type
+
+    Attributes
+    ----------
+    name : str
+        The name of the atom type
+    number : int
+        The integer index of the atom type
+    _member_number : int, private)
+        The order in which this atom type was 'added' this is used to make
+        sure that atom types added last have priority in assignment in the
+        generated hash tables
+    nbfix : dict
+        Dictionary that maps nbfix terms with other atom types. Dict entries
+        are (rmin, epsilon) -- precombined values for that particular atom pair
+
+    Examples
+    --------
     >>> at = AtomType('HA', 1, 1.008, 1)
     >>> at.name, at.number
     ('HA', 1)
@@ -212,34 +223,59 @@ WildCard = WildCard() # Turn it into a singleton
 class Atom(object):
     """ An atom in a structure.
 
-    Parameters:
-        system (str) : Name of the system this atom belongs to
-        name (str): name of the atom
-        type (str or int) : Type of the atom
-        charge (float) : Partial atomic charge (elementary charge units)
-        mass (float) : Atomic mass (amu)
-        props (list) : Other properties from the PSF
-
-    Attributes:
-        - attype (str) : Name of the atom type
-        - system (str) : The system name associated with this atom
-        - name (str) : Name of the atom (str)
-        - charge (float) : Partial atomic charge
-        - mass (float) : Mass of the atom (amu)
-        - idx (int) : index of the atom in the system, starting from 0
-        - props (list) : List of extraneous properties parsed from a PSF
-        - type (AtomType) : If assigned, has additional properties like the
-             non-bonded LJ parameters. If None, it has not yet been assigned
-
-    Possible Attributes (SOA == Set of Atom instances)
-        - bond_partners (SOA) : List of all atoms I am bonded to
-        - angle_partners (SOA) : List of all atoms I am angled to
-        - dihedral_partners (SOA) : List of all atoms I am dihedraled to
-        - bonds (list of Bond's) : All bonds to which I belong
-        - angles (list of Angle's) : All angles to which I belong
-        - dihedrals (list of Dihedral's) : All dihedrals to which I belong
-        - impropers (list of Improper's) : All impropers to which I belong
-        - cmaps (list of Cmap's) : All correction maps to which I belong
+    Parameters
+    ----------
+    system : str
+        Name of the system this atom belongs to
+    name : str
+        name of the atom
+    type : str or int
+        Type of the atom
+    charge : float
+        Partial atomic charge (elementary charge units)
+    mass : float
+        Atomic mass (amu)
+    props : list
+        Other properties from the PSF
+
+    Attributes
+    ----------
+    attype : str
+        Name of the atom type
+    system : str
+        The system name associated with this atom
+    name : str
+        Name of the atom (str)
+    charge : float
+        Partial atomic charge
+    mass : float
+        Mass of the atom (amu)
+    idx : int
+        index of the atom in the system, starting from 0
+    props : list
+        List of extraneous properties parsed from a PSF
+    type : AtomType
+        If assigned, has additional properties like the non-bonded LJ
+        parameters. If None, it has not yet been assigned
+
+    Possible Attributes
+    -------------------
+    bond_partners : set of Atoms
+        List of all atoms I am bonded to
+    angle_partners set of Atoms
+        List of all atoms I am angled to
+    dihedral_partners : et of Atoms
+        List of all atoms I am dihedraled to
+    bonds : list of Bonds
+        All bonds to which I belong
+    angles : list of Angles
+        All angles to which I belong
+    dihedrals : list of Dihedrals
+        All dihedrals to which I belong
+    impropers : list of Impropers
+        All impropers to which I belong
+    cmaps : list of Cmaps
+        All correction maps to which I belong
     """
     def __init__(self, system, name, attype, charge, mass, props=None):
         self.name = name
@@ -450,22 +486,33 @@ class ResidueList(list):
 
     def add_atom(self, system, resnum, resname, name,
                  attype, charge, mass, inscode, props=None):
-        """
-        Adds an atom to the list of residues. If the residue is not the same as
-        the last residue that was created, a new Residue is created and added
-        to this list
-
-        Parameters:
-            - system (str) : The system this atom belongs to
-            - resnum (int) : Residue number
-            - resname (str) : Name of the residue
-            - name (str) : Name of the atom
-            - attype (int or str) : Type of the atom
-            - charge (float) : Partial atomic charge of the atom
-            - mass (float) : Mass (amu) of the atom
-            - inscode (str) : Insertion code, if it is specified
-
-        Returns:
+        """Adds an atom to the list of residues. If the residue is not the same as
+        the last residue that was created, a new Residue is created and added to
+        this list
+
+        Parameters
+        ----------
+        system : str
+            The system this atom belongs to
+        resnum : int
+            Residue number
+        resname : str
+            Name of the residue
+        name : str
+            Name of the atom
+        attype : int or str
+            Type of the atom
+        charge : float
+            Partial atomic charge of the atom
+        mass : float
+            Mass (amu) of the atom
+        inscode : str
+            Insertion code, if it is specified
+        props : list
+            Other properties from the PSF
+
+        Returns
+        -------
             The Atom instance created and added to the list of residues
         """
         lr = self._last_residue
@@ -491,13 +538,16 @@ class ResidueList(list):
 # ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 class Bond(object):
-    """
-    A bond object that links 2 atoms
-
-    Parameters:
-        - atom1 (Atom) : First atom included in the bond
-        - atom2 (Atom) : Second atom included in the bond
-        - bond_type (BondType) : Type for the bond (None if unknown)
+    """A bond object that links 2 atoms
+
+    Parameters
+    ----------
+    atom1 : Atom
+        First atom included in the bond
+    atom2 : Atom
+        Second atom included in the bond
+    bond_type : BondType
+        Type for the bond (None if unknown)
     """
     def __init__(self, atom1, atom2, bond_type=None):
         self.atom1 = atom1
@@ -519,14 +569,18 @@ class Bond(object):
 # ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 class Angle(object):
-    """
-    An angle object that links 3 atoms
-
-    Parameters:
-        - atom1 (Atom) : First atom included in the angle
-        - atom2 (Atom) : Central atom in the valence angle
-        - atom3 (Atom) : Third atom in the valence angle
-        - angle_type (AngleType) : Type for the angle (None if unknown)
+    """An angle object that links 3 atoms
+
+    Parameters
+    ----------
+    atom1 : Atom
+        First atom included in the angle
+    atom2 : Atom
+        Central atom in the valence angle
+    atom3 : Atom
+        Third atom in the valence angle
+    angle_type : AngleType
+        Type for the angle (None if unknown)
     """
     def __init__(self, atom1, atom2, atom3, angle_type=None):
         self.atom1 = atom1
@@ -554,15 +608,17 @@ class Angle(object):
 # ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 class UreyBradley(object):
-    """
-    A harmonic restraint between two atoms separated by 2 valence bonds (i.e.,
-    involved in a valence angle with each other
-
-    Parameters:
-        - atom1 (Atom) : The first atom included in the Urey-Bradley term
-        - atom2 (Atom) : The second atom included in the Urey-Bradley term
-        - ub_type (UreyBradleyType) : The type for the Urey-Bradley term (None
-                                      if unknown)
+    """A harmonic restraint between two atoms separated by 2 valence bonds
+    (i.e., involved in a valence angle with each other
+
+    Parameters
+    ----------
+    atom1 : Atom
+        The first atom included in the Urey-Bradley term
+    atom2 : Atom
+        The second atom included in the Urey-Bradley term
+    ub_type : UreyBradleyType
+        The type for the Urey-Bradley term (None if unknown)
     """
     def __init__(self, atom1, atom2, ub_type=None):
         self.atom1 = atom1
@@ -599,15 +655,20 @@ class UreyBradley(object):
 # ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 class Dihedral(object):
-    """
-    A torsion angle object that links 4 atoms
-
-    Parameters:
-        - atom1 (Atom) : First atom included in the torsion
-        - atom2 (Atom) : Second atom included in the torsion
-        - atom3 (Atom) : Third atom included in the torsion
-        - atom4 (Atom) : Fourth atom included in the torsion
-        - dihedral_type (DihedralType) : Type for the torsion (None if unknown)
+    """A torsion angle object that links 4 atoms
+
+    Parameters
+    ----------
+    atom1 : Atom
+        First atom included in the torsion
+    atom2 : Atom
+        Second atom included in the torsion
+    atom3 : Atom
+        Third atom included in the torsion
+    atom4 : Atom
+        Fourth atom included in the torsion
+    dihedral_type : DihedralType
+        Type for the torsion (None if unknown)
     """
     def __init__(self, atom1, atom2, atom3, atom4, dihedral_type=None):
         self.atom1 = atom1
@@ -648,15 +709,20 @@ class Dihedral(object):
 # ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 class Improper(object):
-    """
-    An improper torsion object. The third atom is bonded to each other atom
-
-    Parameters:
-        - atom1 (Atom) : First atom included in the torsion
-        - atom2 (Atom) : Second atom included in the torsion
-        - atom3 (Atom) : Third atom included in the torsion
-        - atom4 (Atom) : Fourth atom included in the torsion
-        - improper_type (ImproperType) : Type for the improper (None if unknown)
+    """An improper torsion object. The third atom is bonded to each other atom
+
+    Parameters
+    ----------
+    atom1 : Atom
+        First atom included in the torsion
+    atom2 : Atom
+        Second atom included in the torsion
+    atom3 : Atom
+        Third atom included in the torsion
+    atom4 : Atom
+        Fourth atom included in the torsion
+    improper_type : ImproperType
+        Type for the improper (None if unknown)
     """
     def __init__(self, atom1, atom2, atom3, atom4, improper_type=None):
         self.atom1 = atom1
@@ -703,12 +769,14 @@ class Improper(object):
 # ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 class AcceptorDonor(object):
-    """
-    Just a holder for donors and acceptors in CHARMM speak
-    
-    Parameters:
-        - atom1 (Atom) : First atom in the donor/acceptor group
-        - atom2 (Atom) : Second atom in the donor/acceptor group
+    """Just a holder for donors and acceptors in CHARMM speak
+
+    Parameters
+    ----------
+    atom1 : Atom
+        First atom in the donor/acceptor group
+    atom2 : Atom
+        Second atom in the donor/acceptor group
     """
     def __init__(self, atom1, atom2):
         self.atom1 = atom1
@@ -724,13 +792,16 @@ class AcceptorDonor(object):
 # ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 class Group(object):
-    """
-    An 'interacting' group defined by the PSF.
+    """An 'interacting' group defined by the PSF.
 
-    Parameters:
-        - bs (int) : ??
-        - type (int) : The group type
-        - move (int) : If the group moves ??
+    Parameters
+    ----------
+    bs : int
+        ??
+    type : int
+        The group type
+    move : int
+        If the group moves ??
 
     Disclaimer: I really don't know what these numbers mean. I'm speculating
     based on the source code of 'chamber', and this section is simply ignored
@@ -749,36 +820,61 @@ class Cmap(object):
     consecutive correction maps). "Consecutive torsions" (i.e., those definable
     by 5 atoms) will only be recognized if the two torsions have the same order
 
-    Parameters:
-        - atom1 (Atom) : 1st atom of first dihedral
-        - atom2 (Atom) : 2nd atom of first dihedral
-        - atom3 (Atom) : 3rd atom of first dihedral
-        - atom4 (Atom) : 4th atom of first dihedral
-        - atom5 (Atom) : 1st atom of second dihedral
-        - atom6 (Atom) : 2nd atom of second dihedral
-        - atom7 (Atom) : 3rd atom of second dihedral
-        - atom8 (Atom) : 4th atom of second dihedral
-        - cmap_type (CmapType) : Cmap type for this cmap (None if unknown)
-
-    Attributes:
-        - consecutive (bool) : Are the dihedrals consecutive?
+    Parameters
+    ----------
+    atom1 : Atom
+        1st atom of first dihedral
+    atom2 : Atom
+        2nd atom of first dihedral
+    atom3 : Atom
+        3rd atom of first dihedral
+    atom4 : Atom
+        4th atom of first dihedral
+    atom5 : Atom
+        1st atom of second dihedral
+    atom6 : Atom
+        2nd atom of second dihedral
+    atom7 : Atom
+        3rd atom of second dihedral
+    atom8 : Atom
+        4th atom of second dihedral
+    cmap_type : CmapType
+        Cmap type for this cmap (None if unknown)
+
+    Attributes
+    ----------
+    consecutive : bool
+        Are the dihedrals consecutive?
 
     if consecutive:
-        - atom1 (Atom) : 1st atom of 1st dihedral
-        - atom2 (Atom) : 2nd atom of 1st dihedral && 1st atom of 2nd dihedral
-        - atom3 (Atom) : 3rd atom of 1st dihedral && 2nd atom of 2nd dihedral
-        - atom4 (Atom) : 4th atom of 1st dihedral && 3rd atom of 2nd dihedral
-        - atom5 (Atom) :                             4th atom of 2nd dihedral
+        atom1 : Atom
+            1st atom of 1st dihedral
+        atom2 L Atom
+            2nd atom of 1st dihedral && 1st atom of 2nd dihedral
+        atom3 : Atom
+            3rd atom of 1st dihedral && 2nd atom of 2nd dihedral
+        atom4 : Atom
+            4th atom of 1st dihedral && 3rd atom of 2nd dihedral
+        atom5 : Atom
+            4th atom of 2nd dihedral
 
      if not consecutive:
-        - atom1 (Atom) : 1st atom of first dihedral
-        - atom2 (Atom) : 2nd atom of first dihedral
-        - atom3 (Atom) : 3rd atom of first dihedral
-        - atom4 (Atom) : 4th atom of first dihedral
-        - atom5 (Atom) : 1st atom of second dihedral
-        - atom6 (Atom) : 2nd atom of second dihedral
-        - atom7 (Atom) : 3rd atom of second dihedral
-        - atom8 (Atom) : 4th atom of second dihedral
+         atom1 : Atom
+            1st atom of first dihedral
+         atom2 : Atom
+            2nd atom of first dihedral
+         atom3 : Atom
+            3rd atom of first dihedral
+         atom4 : Atom
+            4th atom of first dihedral
+         atom5 : Atom
+            1st atom of second dihedral
+         atom6 : Atom
+            2nd atom of second dihedral
+         atom7 : Atom
+            3rd atom of second dihedral
+         atom8 : Atom
+            4th atom of second dihedral
     """
     def __init__(self, atom1, atom2, atom3, atom4, atom5, atom6, atom7,
                  atom8, cmap_type=None):
@@ -866,9 +962,12 @@ class BondType(object):
     A bond type with an equilibrium length (Angstroms) and force constant
     (kcal/mol/Angstrom^2)
 
-    Parameters:
-        - k (float) : Force constant (kcal/mol/A^2)
-        - req (float) : Equilibrium distance
+    Parameters
+    ----------
+    k : float
+        : Force constant (kcal/mol/A^2)
+    req : float
+        : Equilibrium distance
     """
     def __init__(self, k, req):
         self.k = k
@@ -880,13 +979,15 @@ class BondType(object):
 # ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 class AngleType(object):
-    """
-    An angle type with an equilibrium angle (degrees) and force constant
+    """An angle type with an equilibrium angle (degrees) and force constant
     (kcal/mol/radians^2)
 
-    Parameters:
-        - k (float) : Force constant (kcal/mol/radians^2)
-        - theteq (float) : Equilibrium angle value (degrees)
+    Parameters
+    ----------
+    k : float
+        Force constant (kcal/mol/radians^2)
+    theteq : float
+        Equilibrium angle value (degrees)
     """
     def __init__(self, k, theteq):
         self.k = k
@@ -911,14 +1012,17 @@ NoUreyBradley = UreyBradleyType(None, None)
 # ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 class DihedralType(object):
-    """
-    A torsion angle type with a force constant (kcal/mol), periodicity (int),
-    and phase (degrees)
-
-    Parameters:
-        - phi_k (float) : Force constant (kcal/mol)
-        - per (int) : Periodicity
-        - phase (float): Phase of the torsion
+    """A torsion angle type with a force constant (kcal/mol), periodicity
+    (int), and phase (degrees)
+
+    Parameters
+    ----------
+    phi_k : float
+        Force constant (kcal/mol)
+    per : int
+        Periodicity
+    phase : float
+        Phase of the torsion
     """
     def __init__(self, phi_k, per, phase):
         self.phi_k = float(phi_k)
@@ -936,13 +1040,15 @@ class DihedralType(object):
 # ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 class ImproperType(object):
-    """
-    An improper torsion angle type with a force constant (kcal/mol) and
+    """An improper torsion angle type with a force constant (kcal/mol) and
     equilibrium angle (degrees)
 
-    Parameters:
-        - k (float) : Force constant (kcal/mol)
-        - phieq (int) : Equilibrium angle (degrees)
+    Parameters
+    ----------
+    k : float
+        : Force constant (kcal/mol)
+    phieq : int
+        : Equilibrium angle (degrees)
     """
     def __init__(self, k, phieq):
         self.k = k
@@ -960,10 +1066,13 @@ class CmapType(object):
     """
     Contains a correction map interpolation grid
 
-    Parameters:
-        - resolution (int) : Number of interpolation points for each dihedral
-        - grid (list of floats) : resolution x resolution list of energy values
-                (kcal/mol) for the angles with the 2nd angle changing fastest.
+    Parameters
+    ----------
+    resolution : int
+        Number of interpolation points for each dihedral
+    grid : list of floats
+        resolution x resolution list of energy values (kcal/mol) for the
+        angles with the 2nd angle changing fastest.
 
     The grid object is converted to a _CmapGrid instance which can be treated
     like a normal list, but also has the ability to quickly return a transpose

wrappers/python/simtk/openmm/app/modeller.py

@@ -85,12 +85,16 @@ class Modeller(object):
     def add(self, addTopology, addPositions):
         """Add chains, residues, atoms, and bonds to the model.
 
-        Specify what to add by providing a new Topology object and the corresponding atomic positions.
-        All chains, residues, atoms, and bonds contained in the Topology are added to the model.
-
-        Parameters:
-         - addTopoology (Topology) a Topology whose contents should be added to the model
-         - addPositions (list) the positions of the atoms to add
+        Specify what to add by providing a new Topology object and the
+        corresponding atomic positions. All chains, residues, atoms, and bonds
+        contained in the Topology are added to the model.
+
+        Parameters
+        ----------
+        addTopology : Topology
+            a Topology whose contents should be added to the model
+        addPositions : list
+            the positions of the atoms to add
         """
         # Copy over the existing model.
 
@@ -137,8 +141,11 @@ class Modeller(object):
         You also can specify a bond (as a tuple of Atom objects) to delete just that bond without
         deleting the Atoms it connects.
 
-        Parameters:
-         - toDelete (list) a list of Atoms, Residues, Chains, and bonds (specified as tuples of Atoms) to delete
+        Parameters
+        ----------
+        toDelete : list
+            a list of Atoms, Residues, Chains, and bonds (specified as tuples of
+            Atoms) to delete
         """
         newTopology = Topology()
         newTopology.setPeriodicBoxVectors(self.topology.getPeriodicBoxVectors())
@@ -604,16 +611,28 @@ class Modeller(object):
         Definitions for standard amino acids and nucleotides are built in.  You can call loadHydrogenDefinitions() to load
         additional definitions for other residue types.
 
-        Parameters:
-         - forcefield (ForceField=None) the ForceField to use for determining the positions of hydrogens.  If this is None,
-           positions will be picked which are generally reasonable but not optimized for any particular ForceField.
-         - pH (float=7.0) the pH based on which to select variants
-         - variants (list=None) an optional list of variants to use.  If this is specified, its length must equal the number
-           of residues in the model.  variants[i] is the name of the variant to use for residue i (indexed starting at 0).
-           If an element is None, the standard rules will be followed to select a variant for that residue.
-         - platform (Platform=None) the Platform to use when computing the hydrogen atom positions.  If this is None,
-           the default Platform will be used.
-        Returns: a list of what variant was actually selected for each residue, in the same format as the variants parameter
+        Parameters
+        ----------
+        forcefield : ForceField=None
+            the ForceField to use for determining the positions of hydrogens.
+            If this is None, positions will be picked which are generally
+            reasonable but not optimized for any particular ForceField.
+        pH : float=7.0
+            the pH based on which to select variants
+        variants : list=None
+            an optional list of variants to use.  If this is specified, its
+            length must equal the number of residues in the model.  variants[i]
+            is the name of the variant to use for residue i (indexed starting at
+            0). If an element is None, the standard rules will be followed to
+            select a variant for that residue.
+        platform : Platform=None
+            the Platform to use when computing the hydrogen atom positions.  If
+            this is None, the default Platform will be used.
+
+        Returns
+        -------
+             a list of what variant was actually selected for each residue,
+             in the same format as the variants param
         """
         # Check the list of variants.
 
@@ -862,18 +881,24 @@ class Modeller(object):
         return actualVariants
 
     def addExtraParticles(self, forcefield):
-        """Add missing extra particles to the model that are required by a force field.
-
-        Some force fields use "extra particles" that do not represent actual atoms, but still need to be included in
-        the System.  Examples include lone pairs, Drude particles, and the virtual sites used in some water models
-        to adjust the charge distribution.  Extra particles can be recognized by the fact that their element is None.
-
-        This method is primarily used to add extra particles, but it can also remove them.  It tries to match every
-        residue in the Topology to a template in the force field.  If there is no match, it will both add and remove
-        extra particles as necessary to make it match.
-
-        Parameters:
-         - forcefield (ForceField) the ForceField defining what extra particles should be present
+        """Add missing extra particles to the model that are required by a force
+        field.
+
+        Some force fields use "extra particles" that do not represent
+        actual atoms, but still need to be included in the System.  Examples
+        include lone pairs, Drude particles, and the virtual sites used in some
+        water models to adjust the charge distribution.  Extra particles can be
+        recognized by the fact that their element is None.
+
+        This method is primarily used to add extra particles, but it can also
+        remove them.  It tries to match every residue in the Topology to a
+        template in the force field.  If there is no match, it will both add
+        and remove extra particles as necessary to make it match.
+
+        Parameters
+        ----------
+        forcefield : ForceField
+            the ForceField defining what extra particles should be present
         """
         # Create copies of all residue templates that have had all extra points removed.
 

wrappers/python/simtk/openmm/app/pdbfile.py

@@ -176,9 +176,13 @@ class PDBFile(object):
     def getPositions(self, asNumpy=False, frame=0):
         """Get the atomic positions.
 
-        Parameters:
-         - asNumpy (boolean=False) if true, the values are returned as a numpy array instead of a list of Vec3s
-         - frame (int=0) the index of the frame for which to get positions
+        Parameters
+        ----------
+        asNumpy : boolean=False
+            if true, the values are returned as a numpy array instead of a list
+            of Vec3s
+        frame : int=0
+            the index of the frame for which to get positions
         """
         if asNumpy:
             if self._numpyPositions is None:
@@ -234,13 +238,19 @@ class PDBFile(object):
     def writeFile(topology, positions, file=sys.stdout, keepIds=False):
         """Write a PDB file containing a single model.
 
-        Parameters:
-         - topology (Topology) The Topology defining the model to write
-         - positions (list) The list of atomic positions to write
-         - file (file=stdout) A file to write to
-         - keepIds (bool=False) If True, keep the residue and chain IDs specified in the Topology rather than generating
-           new ones.  Warning: It is up to the caller to make sure these are valid IDs that satisfy the requirements of
-           the PDB format.  Otherwise, the output file will be invalid.
+        Parameters
+        ----------
+        topology : Topology
+            The Topology defining the model to write
+        positions : list
+            The list of atomic positions to write
+        file : file=stdout
+            A file to write to
+        keepIds : bool=False
+            If True, keep the residue and chain IDs specified in the Topology
+            rather than generating new ones.  Warning: It is up to the caller to
+            make sure these are valid IDs that satisfy the requirements of the
+            PDB format.  Otherwise, the output file will be invalid.
         """
         PDBFile.writeHeader(topology, file)
         PDBFile.writeModel(topology, positions, file, keepIds=keepIds)
@@ -250,9 +260,12 @@ class PDBFile(object):
     def writeHeader(topology, file=sys.stdout):
         """Write out the header for a PDB file.
 
-        Parameters:
-         - topology (Topology) The Topology defining the molecular system being written
-         - file (file=stdout) A file to write the file to
+        Parameters
+        ----------
+        topology : Topology
+            The Topology defining the molecular system being written
+        file : file=stdout
+            A file to write the file to
         """
         print("REMARK   1 CREATED WITH OPENMM %s, %s" % (Platform.getOpenMMVersion(), str(date.today())), file=file)
         vectors = topology.getPeriodicBoxVectors()
@@ -266,15 +279,24 @@ class PDBFile(object):
     def writeModel(topology, positions, file=sys.stdout, modelIndex=None, keepIds=False):
         """Write out a model to a PDB file.
 
-        Parameters:
-         - topology (Topology) The Topology defining the model to write
-         - positions (list) The list of atomic positions to write
-         - file (file=stdout) A file to write the model to
-         - modelIndex (int=None) If not None, the model will be surrounded by MODEL/ENDMDL records with this index
-         - keepIds (bool=False) If True, keep the residue and chain IDs specified in the Topology rather than generating
-           new ones.  Warning: It is up to the caller to make sure these are valid IDs that satisfy the requirements of
-           the PDB format.  Otherwise, the output file will be invalid.
+        Parameters
+        ----------
+        topology : Topology
+            The Topology defining the model to write
+        positions : list
+            The list of atomic positions to write
+        file : file=stdout
+            A file to write the model to
+        modelIndex : int=None
+            If not None, the model will be surrounded by MODEL/ENDMDL records
+            with this index
+        keepIds : bool=False
+            If True, keep the residue and chain IDs specified in the Topology
+            rather than generating new ones.  Warning: It is up to the caller to
+            make sure these are valid IDs that satisfy the requirements of the
+            PDB format.  Otherwise, the output file will be invalid.
         """
+
         if len(list(topology.atoms())) != len(positions):
             raise ValueError('The number of positions must match the number of atoms')
         if is_quantity(positions):
@@ -331,9 +353,12 @@ class PDBFile(object):
     def writeFooter(topology, file=sys.stdout):
         """Write out the footer for a PDB file.
 
-        Parameters:
-         - topology (Topology) The Topology defining the molecular system being written
-         - file (file=stdout) A file to write the file to
+        Parameters
+        ----------
+        topology : Topology
+            The Topology defining the molecular system being written
+        file : file=stdout
+            A file to write the file to
         """
         # Identify bonds that should be listed as CONECT records.
 

wrappers/python/simtk/openmm/app/pdbreporter.py

@@ -56,11 +56,23 @@ class PDBReporter(object):
     def describeNextReport(self, simulation):
         """Get information about the next report this object will generate.
 
-        Parameters:
-         - simulation (Simulation) The Simulation to generate a report for
-        Returns: A five element tuple.  The first element is the number of steps until the
-        next report.  The remaining elements specify whether that report will require
-        positions, velocities, forces, and energies respectively.
+        Parameters
+        ----------
+        simulation : Simulation
+            The Simulation to generate a report for
+
+        Returns
+        -------
+        int
+            The number of steps until the
+        bool
+            Requires positions
+        bool
+            Requires velocities
+        bool
+            Requires forces
+        bool
+            Requires energies
         """
         steps = self._reportInterval - simulation.currentStep%self._reportInterval
         return (steps, True, False, False, False)
@@ -68,9 +80,12 @@ class PDBReporter(object):
     def report(self, simulation, state):
         """Generate a report.
 
-        Parameters:
-         - simulation (Simulation) The Simulation to generate a report for
-         - state (State) The current state of the simulation
+        Parameters
+        ----------
+        simulation : Simulation
+            The Simulation to generate a report for
+        state : State
+            The current state of the simulation
         """
         if self._nextModel == 0:
             PDBFile.writeHeader(simulation.topology, self._out)
@@ -95,9 +110,12 @@ class PDBxReporter(PDBReporter):
     def report(self, simulation, state):
         """Generate a report.
 
-        Parameters:
-         - simulation (Simulation) The Simulation to generate a report for
-         - state (State) The current state of the simulation
+        Parameters
+        ----------
+        simulation : Simulation
+            The Simulation to generate a report for
+        state : State
+            The current state of the simulation
         """
         if self._nextModel == 0:
             PDBxFile.writeHeader(simulation.topology, self._out)

wrappers/python/simtk/openmm/app/pdbxfile.py

@@ -193,9 +193,13 @@ class PDBxFile(object):
     def getPositions(self, asNumpy=False, frame=0):
         """Get the atomic positions.
 
-        Parameters:
-         - asNumpy (boolean=False) if true, the values are returned as a numpy array instead of a list of Vec3s
-         - frame (int=0) the index of the frame for which to get positions
+        Parameters
+        ----------
+        asNumpy : bool=False
+            if true, the values are returned as a numpy array instead of a list
+            of Vec3s
+        frame : int=0
+            the index of the frame for which to get positions
         """
         if asNumpy:
             if self._numpyPositions is None:
@@ -210,14 +214,21 @@ class PDBxFile(object):
                   entry=None):
         """Write a PDBx/mmCIF file containing a single model.
 
-        Parameters:
-         - topology (Topology) The Topology defining the model to write
-         - positions (list) The list of atomic positions to write
-         - file (file=stdout) A file to write to
-         - keepIds (bool=False) If True, keep the residue and chain IDs specified in the Topology rather than generating
-           new ones.  Warning: It is up to the caller to make sure these are valid IDs that satisfy the requirements of
-           the PDBx/mmCIF format.  Otherwise, the output file will be invalid.
-         - entry (str=None) The entry ID to assign to the CIF file
+        Parameters
+        ----------
+        topology : Topology
+            The Topology defining the model to write
+        positions : list
+            The list of atomic positions to write
+        file : file=stdout
+            A file to write to
+        keepIds : bool=False
+            If True, keep the residue and chain IDs specified in the Topology
+            rather than generating new ones.  Warning: It is up to the caller to
+            make sure these are valid IDs that satisfy the requirements of the
+            PDBx/mmCIF format.  Otherwise, the output file will be invalid.
+        entry : str=None
+            The entry ID to assign to the CIF file
         """
         PDBxFile.writeHeader(topology, file, entry)
         PDBxFile.writeModel(topology, positions, file, keepIds=keepIds)
@@ -226,10 +237,14 @@ class PDBxFile(object):
     def writeHeader(topology, file=sys.stdout, entry=None):
         """Write out the header for a PDBx/mmCIF file.
 
-        Parameters:
-         - topology (Topology) The Topology defining the molecular system being written
-         - file (file=stdout) A file to write the file to
-         - entry (str=None) The entry ID to assign to the CIF file
+        Parameters
+        ----------
+        topology : Topology
+            The Topology defining the molecular system being written
+        file : file=stdout
+            A file to write the file to
+        entry : str=None
+            The entry ID to assign to the CIF file
         """
         if entry is not None:
             print('data_%s' % entry, file=file)
@@ -280,14 +295,21 @@ class PDBxFile(object):
     def writeModel(topology, positions, file=sys.stdout, modelIndex=1, keepIds=False):
         """Write out a model to a PDBx/mmCIF file.
 
-        Parameters:
-         - topology (Topology) The Topology defining the model to write
-         - positions (list) The list of atomic positions to write
-         - file (file=stdout) A file to write the model to
-         - modelIndex (int=1) The model number of this frame
-         - keepIds (bool=False) If True, keep the residue and chain IDs specified in the Topology rather than generating
-           new ones.  Warning: It is up to the caller to make sure these are valid IDs that satisfy the requirements of
-           the PDBx/mmCIF format.  Otherwise, the output file will be invalid.
+        Parameters
+        ----------
+        topology : Topology
+            The Topology defining the model to write
+        positions : list
+            The list of atomic positions to write
+        file : file=stdout
+            A file to write the model to
+        modelIndex : int=1
+            The model number of this frame
+        keepIds : bool=False
+            If True, keep the residue and chain IDs specified in the Topology
+            rather than generating new ones.  Warning: It is up to the caller to
+            make sure these are valid IDs that satisfy the requirements of the
+            PDBx/mmCIF format.  Otherwise, the output file will be invalid.
         """
         if len(list(topology.atoms())) != len(positions):
             raise ValueError('The number of positions must match the number of atoms')

wrappers/python/simtk/openmm/app/simulation.py

@@ -84,10 +84,14 @@ class Simulation(object):
     def minimizeEnergy(self, tolerance=10*unit.kilojoule/unit.mole, maxIterations=0):
         """Perform a local energy minimization on the system.
 
-        Parameters:
-         - tolerance (energy=10*kilojoules/mole) The energy tolerance to which the system should be minimized
-         - maxIterations (int=0) The maximum number of iterations to perform.  If this is 0, minimization is continued
-           until the results converge without regard to how many iterations it takes.
+        Parameters
+        ----------
+        tolerance : energy=10*kilojoules/mole
+            The energy tolerance to which the system should be minimized
+        maxIterations : int=0
+            The maximum number of iterations to perform.  If this is 0,
+            minimization is continued until the results converge without regard
+            to how many iterations it takes.
         """
         mm.LocalEnergyMinimizer.minimize(self.context, tolerance, maxIterations)
 
@@ -104,15 +108,24 @@ class Simulation(object):
         later resume the simulation.  Another option allows it to write checkpoints or states at regular intervals, so
         you can resume even if the simulation is interrupted before the time limit is reached.
 
-        Parameters:
-         - time (time) the amount of time to run for.  If no units are specified, it is assumed to be a number of hours.
-         - checkpointFile (string or file=None) if specified, a checkpoint file will be written at the end of the
-           simulation (and optionally at regular intervals before then) by passing this to saveCheckpoint().
-         - stateFile (string or file=None) if specified, a state file will be written at the end of the
-           simulation (and optionally at regular intervals before then) by passing this to saveState().
-         - checkpointInterval (time=None) if specified, checkpoints and/or states will be written at regular intervals
-           during the simulation, in addition to writing a final version at the end.  If no units are specified, this is
-           assumed to be in hours.
+        Parameters
+        ----------
+        time : time
+            the amount of time to run for.  If no units are specified, it is
+            assumed to be a number of hours.
+        checkpointFile : string or file=None
+            if specified, a checkpoint file will be written at the end of the
+            simulation (and optionally at regular intervals before then) by
+            passing this to saveCheckpoint().
+        stateFile : string or file=None
+            if specified, a state file will be written at the end of the
+            simulation (and optionally at regular intervals before then) by
+            passing this to saveState().
+        checkpointInterval : time=None
+            if specified, checkpoints and/or states will be written at regular
+            intervals during the simulation, in addition to writing a final
+            version at the end.  If no units are specified, this is assumed to
+            be in hours.
         """
         if unit.is_quantity(time):
             time = time.value_in_unit(unit.hours)
@@ -184,8 +197,11 @@ class Simulation(object):
         another Simulation that has an identical System, uses the same Platform and OpenMM version, and is running on
         identical hardware.  If you need a more portable way to resume simulations, consider using saveState() instead.
 
-        Parameters:
-         - file (string or file) a File-like object to write the checkpoint to, or alternatively a filename
+        Parameters
+        ----------
+        file : string or file
+            a File-like object to write the checkpoint to, or alternatively a
+            filename
         """
         if isinstance(file, str):
             with open(file, 'wb') as f:
@@ -196,8 +212,11 @@ class Simulation(object):
     def loadCheckpoint(self, file):
         """Load a checkpoint file that was created with saveCheckpoint().
 
-        Parameters:
-         - file (string or file) a File-like object to load the checkpoint from, or alternatively a filename
+        Parameters
+        ----------
+        file : string or file
+            a File-like object to load the checkpoint from, or alternatively a
+            filename
         """
         if isinstance(file, str):
             with open(file, 'rb') as f:
@@ -217,8 +236,11 @@ class Simulation(object):
         with the original Simulation.  On the other hand, this means it is portable across different Platforms or
         hardware.
 
-        Parameters:
-         - file (string or file) a File-like object to write the state to, or alternatively a filename
+        Parameters
+        ----------
+        file : string or file
+            a File-like object to write the state to, or alternatively a
+            filename
         """
         state = self.context.getState(getPositions=True, getVelocities=True, getParameters=True)
         xml = mm.XmlSerializer.serialize(state)
@@ -231,8 +253,11 @@ class Simulation(object):
     def loadState(self, file):
         """Load a State file that was created with saveState().
 
-        Parameters:
-         - file (string or file) a File-like object to load the state from, or alternatively a filename
+        Parameters
+        ----------
+        file : string or file
+            a File-like object to load the state from, or alternatively a
+            filename
         """
         if isinstance(file, str):
             with open(file, 'r') as f:

wrappers/python/simtk/openmm/app/statedatareporter.py

@@ -129,11 +129,23 @@ class StateDataReporter(object):
     def describeNextReport(self, simulation):
         """Get information about the next report this object will generate.
 
-        Parameters:
-         - simulation (Simulation) The Simulation to generate a report for
-        Returns: A five element tuple.  The first element is the number of steps until the
-        next report.  The remaining elements specify whether that report will require
-        positions, velocities, forces, and energies respectively.
+        Parameters
+        ----------
+        simulation : Simulation
+            The Simulation to generate a report for
+
+        Returns
+        -------
+        int
+            The number of steps until the
+        bool
+            Requires positions
+        bool
+            Requires velocities
+        bool
+            Requires forces
+        bool
+            Requires energies
         """
         steps = self._reportInterval - simulation.currentStep%self._reportInterval
         return (steps, self._needsPositions, self._needsVelocities, self._needsForces, self._needEnergy)
@@ -141,9 +153,12 @@ class StateDataReporter(object):
     def report(self, simulation, state):
         """Generate a report.
 
-        Parameters:
-         - simulation (Simulation) The Simulation to generate a report for
-         - state (State) The current state of the simulation
+        Parameters
+        ----------
+        simulation : Simulation
+            The Simulation to generate a report for
+        state : State
+            The current state of the simulation
         """
         if not self._hasInitialized:
             self._initializeConstants(simulation)

wrappers/python/simtk/openmm/app/topology.py

@@ -89,10 +89,15 @@ class Topology(object):
     def addChain(self, id=None):
         """Create a new Chain and add it to the Topology.
 
-        Parameters:
-         - id (string=None) An optional identifier for the chain.  If this is omitted, an id
-           is generated based on the chain index.
-        Returns: the newly created Chain
+        Parameters
+        ----------
+        id : string=None
+            An optional identifier for the chain.  If this is omitted, an id is
+            generated based on the chain index.
+
+        Returns
+        -------
+             the newly created Chain
         """
         if id is None:
             id = str(len(self._chains)+1)
@@ -103,12 +108,19 @@ class Topology(object):
     def addResidue(self, name, chain, id=None):
         """Create a new Residue and add it to the Topology.
 
-        Parameters:
-         - name (string) The name of the residue to add
-         - chain (Chain) The Chain to add it to
-         - id (string=None) An optional identifier for the residue.  If this is omitted, an id
+        Parameters
+        ----------
+        name : string
+            The name of the residue to add
+        chain : Chain
+            The Chain to add it to
+        id : string=None
+            An optional identifier for the residue.  If this is omitted, an id
             is generated based on the residue index.
-        Returns: the newly created Residue
+
+        Returns
+        -------
+             the newly created Resid
         """
         if id is None:
             id = str(self._numResidues+1)
@@ -120,13 +132,21 @@ class Topology(object):
     def addAtom(self, name, element, residue, id=None):
         """Create a new Atom and add it to the Topology.
 
-        Parameters:
-         - name (string) The name of the atom to add
-         - element (Element) The element of the atom to add
-         - residue (Residue) The Residue to add it to
-         - id (string=None) An optional identifier for the atom.  If this is omitted, an id
-           is generated based on the atom index.
-        Returns: the newly created Atom
+        Parameters
+        ----------
+        name : string
+            The name of the atom to add
+        element : Element
+            The element of the atom to add
+        residue : Residue
+            The Residue to add it to
+        id : string=None
+            An optional identifier for the atom.  If this is omitted, an id is
+            generated based on the atom index.
+
+        Returns
+        -------
+             the newly created Atom
         """
         if id is None:
             id = str(self._numAtoms+1)
@@ -138,9 +158,12 @@ class Topology(object):
     def addBond(self, atom1, atom2):
         """Create a new bond and add it to the Topology.
 
-        Parameters:
-         - atom1 (Atom) The first Atom connected by the bond
-         - atom2 (Atom) The second Atom connected by the bond
+        Parameters
+        ----------
+        atom1 : Atom
+            The first Atom connected by the bond
+        atom2 : Atom
+            The second Atom connected by the bond
         """
         self._bonds.append((atom1, atom2))
 
@@ -274,10 +297,13 @@ class Topology(object):
                             self.addBond(atomMaps[fromResidue][fromAtom], atomMaps[toResidue][toAtom])
 
     def createDisulfideBonds(self, positions):
-        """Identify disulfide bonds based on proximity and add them to the Topology.
+        """Identify disulfide bonds based on proximity and add them to the
+        Topology.
 
-        Parameters:
-         - positions (list) The list of atomic positions based on which to identify bonded atoms
+        Parameters
+        ----------
+        positions : list
+            The list of atomic positions based on which to identify bonded atoms
         """
         def isCyx(res):
             names = [atom.name for atom in res._atoms]

wrappers/python/simtk/unit/unit.py

@@ -54,9 +54,12 @@ class Unit(object):
     def __init__(self, base_or_scaled_units):
         """Create a new Unit.
 
-        Parameters:
-         - self (Unit) The newly created Unit.
-         - base_or_scaled_units (dict) Keys are BaseUnits or ScaledUnits.  Values are exponents (numbers).
+        Parameters
+        ----------
+        self : Unit
+            The newly created Unit.
+        base_or_scaled_units : dict
+            Keys are BaseUnits or ScaledUnits.  Values are exponents (numbers).
         """
         # Unit contents are of two types: BaseUnits and ScaledUnits
         self._top_base_units = {}
@@ -389,7 +392,8 @@ class Unit(object):
         Strips off any ScaledUnits in the Unit, leaving only BaseUnits.
 
         Parameters
-         - system: a dictionary of (BaseDimension, BaseUnit) pairs
+        ----------
+        system : a dictionary of (BaseDimension, BaseUnit) pairs
         """
         return system.express_unit(self)
 
@@ -583,7 +587,7 @@ class UnitSystem(object):
 
     Parameters
     ----------
-    units: ``list``
+    units : list
         List of base units from which to construct the unit system
     """
     def __init__(self, units):
@@ -678,7 +682,7 @@ def is_unit(x):
     Returns True if x is a Unit, False otherwise.
 
     Examples
-
+    --------
     >>> is_unit(16)
     False
     """

wrappers/python/src/swig_doxygen/OpenMM.i

@@ -45,7 +45,7 @@ using namespace OpenMM;
 
 %}
 
-%feature("autodoc", "1");
+%feature("autodoc", "0");
 %nodefaultctor;
 
 %include features.i

wrappers/python/src/swig_doxygen/swigInputBuilder.py

@@ -146,6 +146,20 @@ def getClassMethodList(classNode, skipMethods):
     return methodList
 
 
+def docstringTypemap(cpptype):
+    """Translate a C++ type to Python for inclusion in the Python docstrings.
+    This doesn't need to be perfectly accurate -- it's not used for generating
+    the actual swig wrapper code. It's only used for generating the docstrings.
+    """
+    pytype = cpptype
+    if pytype.startswith('const '):
+        pytype = pytype[6:]
+    if pytype.startswith('std::'):
+        pytype = pytype[5:]
+    pytype = pytype.strip('&')
+    return pytype.strip()
+
+
 class SwigInputBuilder:
     def __init__(self,
                  inputDirname,
@@ -563,32 +577,58 @@ class SwigInputBuilder:
             (shortClassName, memberNode,
              shortMethDefinition, methName,
              isConstructors, isDestructor, templateType, templateName ) = items
+
             if self.fOutDocstring:
-                for dNode in findNodes(memberNode, 'detaileddescription'):
-                    dString=""
+                signatureParams = findNodes(memberNode, 'param')
+                assert len(findNodes(memberNode, 'detaileddescription')) == 1
+                dNode = findNodes(memberNode, 'detaileddescription')[0]
+
                 try:
                     description=getText('para', dNode)
                     description.strip()
-                        if description:
-                            dString=description
                 except IndexError:
-                        pass
+                    description = ''
                 params = findNodes(dNode, 'para/parameterlist/parameteritem')
+
+                paramString = ['Parameters', '----------']
+                returnString = ['Returns', '-------']
+
                 if len(params) > 0:
-                        dString="%s\n   Parameters:" % dString
-                    for pNode in params:
-                        argName = getText('parameternamelist/parametername', pNode)
+                    if len(signatureParams) != len(params):
+                        raise ValueError('docstring in %s.%s does not match the signature' % (shortClassName, methName))
+
+                    for pNode, pSignatureNode in zip(params, signatureParams):
+                        parameterNameNode = findNodes(pNode, 'parameternamelist/parametername')[0]
                         argDoc = getText('parameterdescription/para', pNode)
-                        dString="%s\n    - %s %s" % (dString, argName, argDoc)
-                        dString.strip()
+                        argName = getNodeText(parameterNameNode)
+                        argType = docstringTypemap(getText('type', pSignatureNode))
+
+                        isOutput = parameterNameNode.get('direction') == 'out'
+                        if isOutput:
+                            returnString.extend(['%s : %s' % (argName, argType), '    %s' % argDoc])
+                        else:
+                            paramString.extend(['%s : %s' % (argName, argType), '    %s' % argDoc])
+
+
+                returnSection = findNodes(dNode, 'para/simplesect')
+                if len(returnSection) > 0:
+                    returnNode = returnSection[0]
+                    if returnNode.get('kind') == 'return':
+                        argType = getNodeText(findNodes(memberNode, 'type')[0])
+                        argType = docstringTypemap(argType)
+                        returnString.extend([argType, '    %s' % getNodeText(returnNode).strip()])
+
+                dString = '\n'.join(
+                    ([description] + [''] if len(description) > 0 else []) +
+                    (paramString + [''] if len(paramString) > 2 else []) +
+                    (returnString if len(returnString) > 2 else [])).strip()
                 if dString:
-                        dString=re.sub(r'([^\\])"', r'\g<1>\"', dString)
+                    dString = re.sub(r'([^\\])"', r'\g<1>\"', dString)
                     s = '%%feature("docstring") OpenMM::%s::%s "%s";' \
                        % (shortClassName, methName, dString)
                     self.fOutDocstring.write("%s\n" % s)
-                self.fOutDocstring.write("\n\n")
-        #print "Done write Docstring info\n"
 
+                self.fOutDocstring.write("\n\n")
 
 
     def writeSwigFile(self):