Merge pull request #912 from jbarnoud/docs

Some fixes for the formatting of the documentation

package/MDAnalysis/analysis/align.py

@@ -165,6 +165,7 @@
 The following functions are used by the other functions in this
 module. They are probably of more interest to developers than to
 normal users.
+
 .. autofunction:: _fit_to
 .. autofunction:: fasta2select
 .. autofunction:: get_matching_atoms
@@ -198,6 +199,7 @@ def rotation_matrix(a, b, weights=None):
     reference structure):
 
     .. math::
+
         \vec{b} = \bold{R} \dot \vec{a}
 
     Parameters
@@ -239,9 +241,10 @@ def rotation_matrix(a, b, weights=None):
 
     See Also
     --------
-    :func:`rmsd` calculates the RMSD between *a* and *b*; for fitting a whole
-    trajectory it is more efficient to use :func:`rms_fit_trj`. A complete fit
-    of two structures can be done with :func:`alignto`. """
+    MDAnalysis.analysis.rms.rmsd: Calculates the RMSD between *a* and *b*.
+    alignto: A complete fit of two structures.
+    AlignTraj: Fit a whole trajectory.
+    """
 
     a = np.asarray(a, dtype=np.float64)
     b = np.asarray(b, dtype=np.float64)
@@ -382,8 +385,10 @@ def alignto(mobile, reference, select="all", mass_weighted=False,
     new_rmsd
         RMSD after spatial alignment.
 
-    .. SeeAlso:: For RMSD-fitting trajectories it is more efficient to
-                 use :class:`AlignTraj`.
+    See Also
+    --------
+    AlignTraj: More efficient method for RMSD-fitting trajectories.
+
 
     .. versionchanged:: 0.8
        Added check that the two groups describe the same atoms including
@@ -393,7 +398,6 @@ def alignto(mobile, reference, select="all", mass_weighted=False,
        Uses :func:`get_matching_atoms` to work with incomplete selections
        and new *strict* keyword. The new default is to be lenient whereas
        the old behavior was the equivalent of *strict* = ``True``.
-
     """
     if select in ('all', None):
         # keep the EXACT order in the input AtomGroups; select_atoms('all')

package/MDAnalysis/analysis/base.py

@@ -31,17 +31,19 @@
 
 
 class AnalysisBase(object):
-    """Base class for defining multi frame analysis, it is designed as a
-    template for creating multiframe analysis. This class will automatically
-    take care of setting up the trajectory reader for iterating and offers to
-    show a progress meter.
+    """Base class for defining multi frame analysis
+    
+    The class it is designed as a template for creating multiframe analyses.
+    This class will automatically take care of setting up the trajectory
+    reader for iterating, and it offers to show a progress meter.
 
     To define a new Analysis, `AnalysisBase` needs to be subclassed
     `_single_frame` must be defined. It is also possible to define
     `_prepare` and `_conclude` for pre and post processing. See the example
     below.
 
     .. code-block:: python
+
        class NewAnalysis(AnalysisBase):
            def __init__(self, atomgroup, parameter, **kwargs):
                super(NewAnalysis, self).__init__(atomgroup.universe.trajectory,
@@ -70,6 +72,7 @@ def _conclude(self):
     Afterwards the new analysis can be run like this.
 
     .. code-block:: python
+
        na = NewAnalysis(u.select_atoms('name CA'), 35).run()
        print(na.result)
 

package/MDAnalysis/analysis/contacts.py

@@ -14,7 +14,7 @@
 # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787
 #
 
-"""\
+"""
 ================================================================
 Native contacts analysis --- :mod:`MDAnalysis.analysis.contacts`
 ================================================================
@@ -97,8 +97,8 @@
 
 Suggested cutoff distances for different simulations
 
-* For all-atom simulations, cutoff = 4.5 A
-* For coarse-grained simulations, cutoff = 6.0 A
+* For all-atom simulations, cutoff = 4.5 Å
+* For coarse-grained simulations, cutoff = 6.0 Å
 
 
 Two-dimensional contact analysis (q1-q2)
@@ -377,8 +377,7 @@ class Contacts(AnalysisBase):
     """
     def __init__(self, u, selection, refgroup, method="hard_cut", radius=4.5,
                  kwargs=None, **basekwargs):
-        """Initialization
-
+        """
         Parameters
         ----------
         u : Universe
@@ -565,13 +564,12 @@ class ContactAnalysis(object):
     def __init__(self, topology, trajectory, ref1=None, ref2=None, radius=8.0,
                  targetdir=os.path.curdir, infix="", force=False,
                  selection="name CA", centroids=False):
-        """Calculate native contacts from two reference structures.
-
+        """
         Parameters
         ----------
-        topology : filename
+        topology : filename as str
             topology file
-        trajectory : filename
+        trajectory : filename as str
             trajectory
         ref1 : filename or ``None``, optional
             structure of the reference conformation 1 (pdb); if ``None`` the
@@ -1026,6 +1024,7 @@ def run(self, store=True, force=False, start=0, stop=None, step=1,
         Stores results in :attr:`ContactAnalysis1.timeseries` (if store=True)
         and writes them to a data file. The average q is written to a second
         data file.
+
         *start*
             The value of the first frame index in the trajectory to be used
             (default: index 0)
@@ -1150,9 +1149,7 @@ def load(self, filename):
     def plot(self, filename=None, **kwargs):
         """Plot q(t).
 
-        .. function:: ContactAnalysis1.plot([filename, ...])
-
-        If *filename* is supplied then the figure is also written to file (the
+        If `filename` is supplied then the figure is also written to file (the
         suffix determines the file type, e.g. pdf, png, eps, ...). All other
         keyword arguments are passed on to :func:`pylab.plot`.
         """
@@ -1197,8 +1194,6 @@ def _plot_qavg_pcolor(self, filename=None, **kwargs):
     def plot_qavg(self, filename=None, **kwargs):
         """Plot :attr:`ContactAnalysis1.qavg`, the matrix of average native contacts.
 
-        .. function:: ContactAnalysis1.plot_qavg([filename, ...])
-
         If *filename* is supplied then the figure is also written to file (the
         suffix determines the file type, e.g. pdf, png, eps, ...). All other
         keyword arguments are passed on to :func:`pylab.imshow`.

package/MDAnalysis/analysis/distances.py

@@ -25,10 +25,11 @@
 :func:`dist` and :func:`between` can take atom groups that do not even
 have to be from the same :class:`~MDAnalysis.core.AtomGroup.Universe`.
 
-.. SeeAlso:: :mod:`MDAnalysis.lib.distances` 
+.. SeeAlso:: :mod:`MDAnalysis.lib.distances`
 """
 
-__all__ = ['distance_array', 'self_distance_array', 'contact_matrix', 'dist']
+__all__ = ['distance_array', 'self_distance_array',
+           'contact_matrix', 'dist', 'between']
 
 import numpy as np
 
@@ -84,12 +85,12 @@ def contact_matrix(coord, cutoff=15.0, returntype="numpy", box=None):
 
     Note
     ----
-    :module:`scipy.sparse` is require for using *sparse* matrices; if it cannot
+    :mod:`scipy.sparse` is require for using *sparse* matrices; if it cannot
     be imported then an `ImportError` is raised.
 
+
     .. versionchanged:: 0.11.0
        Keyword *suppress_progmet* and *progress_meter_freq* were removed.
-
     '''
 
     if returntype == "numpy":
@@ -124,8 +125,7 @@ def dist(A, B, offset=0):
 
     Arguments
     ---------
-
-    A, B: AtomGroup instances
+    A, B : AtomGroup
        :class:`~MDAnalysis.core.AtomGroup.AtomGroup` with the
        same number of atoms
     offset : integer or tuple, optional, default 0
@@ -145,7 +145,6 @@ def dist(A, B, offset=0):
        residue ids of the `B` group (possibly changed with `offset`)
     distances : array
        distances between the atoms
-
     """
     if A.atoms.n_atoms != B.atoms.n_atoms:
         raise ValueError("AtomGroups A and B do not have the same number of atoms")
@@ -171,7 +170,6 @@ def between(group, A, B, distance):
 
     Parameters
     ----------
-
     group : AtomGroup
         Find members of `group` that are between `A` and `B`
     A, B : AtomGroups
@@ -185,11 +183,11 @@ def between(group, A, B, distance):
     Returns
     -------
     AtomGroup
-       :class:`~MDAnalysis.core.AtomGroup.AtomGroup` of atoms that
-       fulfill the criterion
+        :class:`~MDAnalysis.core.AtomGroup.AtomGroup` of atoms that
+        fulfill the criterion
 
-    .. versionadded: 0.7.5
 
+    .. versionadded: 0.7.5
     """
     from MDAnalysis.core.AtomGroup import AtomGroup
 

package/MDAnalysis/analysis/hbonds/hbond_autocorrel.py

@@ -32,7 +32,8 @@
 then the lifetime of these bonds is monitored over time.  Multiple passes
 through the trajectory are used to build an average of the behaviour.
 
-    :math:`C_x(t) = \\left \\langle \\frac{h_{ij}(t_0) h_{ij}(t_0 + t)}{h_{ij}(t_0)^2} \\right\\rangle`
+.. math::
+   C_x(t) = \\left \\langle \\frac{h_{ij}(t_0) h_{ij}(t_0 + t)}{h_{ij}(t_0)^2} \\right\\rangle
 
 The subscript :math:`x` refers to the definition of lifetime being used, either
 continuous or intermittent.  The continuous definition measures the time that
@@ -41,7 +42,8 @@
 be counted again.  The relevent lifetime, :math:`\\tau_x`, can then be found
 via integration of this function
 
-    :math:`\\tau_x = \\int_0^\\infty C_x(t) dt`
+.. math::
+   \\tau_x = \\int_0^\\infty C_x(t) dt`
 
 For this, the observed behaviour is fitted to a multi exponential function,
 using 2 exponents for the continuous lifetime and 3 for the intermittent
@@ -277,8 +279,8 @@ def _slice_traj(self, sample_time):
     def run(self, force=False):
         """Run all the required passes
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
         force : bool, optional
             Will overwrite previous results if they exist
         """

package/MDAnalysis/analysis/lineardensity.py

@@ -35,20 +35,15 @@ class LinearDensity(AnalysisBase):
 
     Parameters
     ----------
-    selection : `AtomGroup` object
+    selection : AtomGroup
       Any atomgroup
-
-    Keywords
-    --------
     grouping : str {'atoms', 'residues', 'segments', 'fragments'}
           Density profiles will be computed on the center of geometry
           of a selected group of atoms ['atoms']
-
     binsize : float
           Bin width in Angstrom used to build linear density
           histograms. Defines the resolution of the resulting density
           profile (smaller --> higher resolution) [0.25]
-
     start : int
           The frame to start at [0]
     stop : int
@@ -59,14 +54,17 @@ class LinearDensity(AnalysisBase):
     Example
     -------
     First create a LinearDensity object by supplying a selection,
-    then use the `run` method:
+    then use the :meth:`run` method::
+
       ldens = LinearDensity(selection)
       ldens.run()
 
-    Density profiles can be written to file through the `save` method:
+    Density profiles can be written to file through the `save` method::
+
       ldens.save(description='mydensprof', form='txt')
+
     which will output the density profiles in a file named
-    <trajectory_filename>.mydensprof_<grouping>.ldens
+    `<trajectory_filename>.mydensprof_<grouping>.ldens`.
     Results can be saved in npz format by specifying `form='npz'`
 
     .. versionadded:: 0.14.0
@@ -188,8 +186,8 @@ def save(self, description='', form='txt'):
         binary numpy npz file. Output file has extension 'ldens' and begins
         with the name of the trajectory file.
 
-        Keywords
-        --------
+        Parameters
+        ----------
         description : str
           An arbitrary description added to the output filename. Can be useful
         form : str {'txt', 'npz'}
@@ -199,10 +197,12 @@ def save(self, description='', form='txt'):
         Example
         -------
         After initializing and running a `LinearDensity` object, results can be
-        written to file as follows:
+        written to file as follows::
+
           ldens.save(description='mydensprof', form='txt')
+
         which will output the linear density profiles in a file named
-        <trajectory_filename>.mydensprof_<grouping>.ldens
+        `<trajectory_filename>.mydensprof_<grouping>.ldens`.
 
         """
         # Take root of trajectory filename for output file naming

package/MDAnalysis/analysis/rms.py

@@ -96,7 +96,6 @@
    fig.savefig("rmsd_all_CORE_LID_NMP_ref1AKE.pdf")
 
 
-
 Functions
 ---------
 
@@ -325,13 +324,13 @@ def __init__(self, traj, reference=None, select='all',
         ref_frame : int (optional)
              frame index to select frame from `reference`
 
+
         .. _ClustalW: http://www.clustal.org/
         .. _STAMP: http://www.compbio.dundee.ac.uk/manuals/stamp.4.2/
 
         .. versionadded:: 0.7.7
         .. versionchanged:: 0.8
            *groupselections* added
-
         """
         self.universe = traj
         if reference is None:
@@ -580,8 +579,9 @@ def run(self, start=0, stop=-1, step=1, progout=10, quiet=False):
 
         References
         ----------
-        [Welford1962] B. P. Welford (1962). "Note on a Method for Calculating
-           Corrected Sums of Squares and Products." Technometrics 4(3):419-420.
+        .. [Welford1962] B. P. Welford (1962). "Note on a Method for
+           Calculating Corrected Sums of Squares and Products." Technometrics
+           4(3):419-420.
         """
         sumsquares = np.zeros((self.atomgroup.n_atoms, 3))
         means = np.array(sumsquares)