Fix some documentation rendering issues

Minor missformatting of docstring can cause part of the documentation
not to be rendered. This commit fixes some of this formatting issues. In
some occurences, it also updates some docstring refering to deprecated
methods.

The commit also restores the documentation for gromacs trajectory
formats.

Fixes 855

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)