fix sphinx warnings

.travis.yml

@@ -22,7 +22,7 @@ env:
     - BUILD_DOCS=false
     - PYTHON_VERSION=2.7
     - MAIN_CMD="python ./testsuite/MDAnalysisTests/mda_nosetests --processes=2 --process-timeout=400 --no-open-files --with-timer --timer-top-n 50"
-    - MAIN_CMD_OPTIONS=""
+    - SETUP_CMD=""
     - COVERALLS=false
     - BUILD_CMD="pip install -v package/ && pip install testsuite/"
     - CONDA_DEPENDENCIES="mmtf-python nose=1.3.7 mock six biopython networkx cython joblib nose-timer"
@@ -33,14 +33,15 @@ env:
     - CONDA_CHANNEL_PRIORITY=True
     - NUMPY_VERSION=stable
   matrix:
-    - NAME='minimal' PYTHON_VERSION=2.7 MAIN_CMD_OPTIONS='--with-memleak'
+    - NAME='minimal' PYTHON_VERSION=2.7 SETUP_CMD='--with-memleak'
 
 matrix:
   fast_finish: true
   include:
     - os: linux
       env: NAME="Doc"
-           MAIN_CMD="cd package && python setup.py build_sphinx"
+           MAIN_CMD="cd package && python setup.py"
+           SETUP_CMD="build_sphinx"
            BUILD_DOCS=true
            BUILD_CMD="cd ${TRAVIS_BUILD_DIR}/package && python setup.py build_ext --inplace"
            CONDA_DEPENDENCIES=${CONDA_ALL_DEPENDENCIES}
@@ -54,7 +55,7 @@ matrix:
 
     - os: linux
       env: NAME='full'
-           MAIN_CMD_OPTIONS='--with-coverage --cover-package MDAnalysis'
+           SETUP_CMD='--with-coverage --cover-package MDAnalysis'
            CONDA_DEPENDENCIES=${CONDA_ALL_DEPENDENCIES}
            COVERALLS='true'
 
@@ -83,14 +84,13 @@ install:
         HOLE_BINDIR="${HOME}/${MDA_OPTPACKAGES}/hole2/exe"; \
         export PATH=${PATH}:${HOLE_BINDIR}; \
     fi
-  - if [[ $BUILD_DOCS == "true" ]] ; then conda install sphinx=1.5.1; fi
   - eval $BUILD_CMD
 
 script:
   - cd ${TRAVIS_BUILD_DIR}
   - if [[ $TRAVIS_OS_NAME == 'osx' ]]; then ulimit -S -n 2048; fi
-  - echo $MAIN_CMD $MAIN_CMD_OPTIONS
-  - eval $MAIN_CMD $MAIN_CMD_OPTIONS
+  - echo $MAIN_CMD $SETUP_CMD
+  - eval $MAIN_CMD $SETUP_CMD
 
 after_success:
   - if [[ $COVERALLS == 'true' ]]; then coveralls; fi

package/.pylintrc

@@ -118,7 +118,6 @@ enable=abstract-class-instantiated,
        invalid-slots,
        invalid-slots-object,
        invalid-star-assignment-target,
-       invalid-unary-operand-type,
        logging-format-truncated,
        logging-not-lazy,
        logging-too-few-args,
@@ -156,7 +155,6 @@ enable=abstract-class-instantiated,
        old-octal-literal,
        old-raise-syntax,
        parameter-unpacking,
-       raising-bad-type,
        raising-non-exception,
        raising-string,
        raw_input-builtin,
@@ -270,6 +268,8 @@ enable=abstract-class-instantiated,
        # used-before-assignment,
        # wildcard-import,
        # wrong-import-order,
+       # invalid-unary-operand-type,
+       # raising-bad-type,
 
 
 [REPORTS]

package/CHANGELOG

@@ -24,8 +24,12 @@ Enhancements
   * Residues with the same residue ids are not merged by default now 
     (apply to PDB, GRO) (Issue #1306)
 
+Fixes
+  * Various documentation sphinx errors (PR #1312)
+
 Changes
   * Enable various pylint warnings to increase python 3 compatibility
+  * Change Mathjax cdn (Issue #1313)
 
 04/10/17 kain88-de, fiona-naughton, richardjgowers, tyler.je.reddy, jdetle
          euhruska, orbeckst, rbrtdlg, jbarnoud, wouterboomsma, shanmbic,

package/MDAnalysis/analysis/align.py

@@ -552,20 +552,21 @@ def __init__(self, mobile, reference, select='all', filename=None,
 
         Notes
         -----
-        If set to `verbose=False`, it is recommended to wrap the statement in a
-        ``try ...  finally`` to guarantee restoring of the log level in the
-        case of an exception.
+        - If set to ``verbose=False``, it is recommended to wrap the statement in a
+          ``try ...  finally`` to guarantee restoring of the log level in the
+          case of an exception.
+        - The ``in_memory`` option changes the `mobile` universe to an
+          in-memory representation (see :mod:`MDAnalysis.coordinates.memory`)
+          for the remainder of the Python session. If ``mobile.trajectory`` is
+          already a :class:`MemoryReader` then it is *always* treated as if
+          ``in_memory`` had been set to ``True``.
 
-        The `in_memory` option changes the `mobile` universe to an in-memory
-        representation (see :mod:`MDAnalysis.coordinates.memory`) for the
-        remainder of the Python session. If ``mobile.trajectory```is already a
-        :class:`MemoryReader` then it is *always* treated as if `in_memory` had
-        been set to ``True``.
 
         .. versionchanged:: 0.16.0
-           new general 'weights' kwarg replace mass_weights, deprecated 'mass_weights'
+           new general ``weights`` kwarg replace ``mass_weights``
+
         .. deprecated:: 0.16.0
-           Instead of ``mass_weighted=True`` use new ``weights='mass'`
+           Instead of ``mass_weighted=True`` use new ``weights='mass'``
 
         """
         select = rms.process_selection(select)

package/MDAnalysis/analysis/contacts.py

@@ -536,7 +536,6 @@ def q1q2(u, selection='all', radius=4.5,
 # until then it remains because we don't have the functionality
 # elsewhere.
 
-@deprecate(new_name="Contacts", message="This class will be removed in 0.17")
 class ContactAnalysis(object):
     """Perform a native contact analysis ("q1-q2").
 
@@ -564,48 +563,47 @@ class ContactAnalysis(object):
     accessible as the attribute
     :attr:`ContactAnalysis.timeseries`.
 
+    Parameters
+    ----------
+    topology : filename as str
+        topology file
+    trajectory : filename as str
+        trajectory
+    ref1 : filename or ``None``, optional
+        structure of the reference conformation 1 (pdb); if ``None`` the
+        *first* frame of the trajectory is chosen
+    ref2 : filename or ``None``, optional
+        structure of the reference conformation 2 (pdb); if ``None`` the
+        *last* frame of the trajectory is chosen
+    radius : float, optional, default 8 A
+        contacts are deemed any Ca within radius
+    targetdir : path, optional, default ``.``
+        output files are saved in this directory
+    infix : string, optional
+        additional tag string that is inserted into the output filename of
+        the data file
+     selection : string, optional, default ``"name CA"``
+        MDAnalysis selection string that selects the particles of
+        interest; the default is to only select the C-alpha atoms
+        in `ref1` and `ref2`
+
+        .. Note:: If `selection` produces more than one atom per
+                  residue then you will get multiple contacts per
+                  residue unless you also set `centroids` = ``True``
+     centroids : bool
+        If set to ``True``, use the centroids for the selected atoms on a
+        per-residue basis to compute contacts. This allows, for instance
+        defining the sidechains as `selection` and then computing distances
+        between sidechain centroids.
+
 
     .. deprecated:: 0.15.0
     """
 
+    @deprecate(new_name="Contacts", message="This class will be removed in 0.17")
     def __init__(self, topology, trajectory, ref1=None, ref2=None, radius=8.0,
                  targetdir=os.path.curdir, infix="", force=False,
                  selection="name CA", centroids=False):
-        """
-        Parameters
-        ----------
-        topology : filename as str
-            topology file
-        trajectory : filename as str
-            trajectory
-        ref1 : filename or ``None``, optional
-            structure of the reference conformation 1 (pdb); if ``None`` the
-            *first* frame of the trajectory is chosen
-        ref2 : filename or ``None``, optional
-            structure of the reference conformation 2 (pdb); if ``None`` the
-            *last* frame of the trajectory is chosen
-        radius : float, optional, default 8 A
-            contacts are deemed any Ca within radius
-        targetdir : path, optional, default ``.``
-            output files are saved in this directory
-        infix : string, optional
-            additional tag string that is inserted into the output filename of
-            the data file
-         selection : string, optional, default ``"name CA"``
-            MDAnalysis selection string that selects the particles of
-            interest; the default is to only select the C-alpha atoms
-            in `ref1` and `ref2`
-
-            .. Note:: If `selection` produces more than one atom per
-                      residue then you will get multiple contacts per
-                      residue unless you also set `centroids` = ``True``
-         centroids : bool
-            If set to ``True``, use the centroids for the selected atoms on a
-            per-residue basis to compute contacts. This allows, for instance
-            defining the sidechains as `selection` and then computing distances
-            between sidechain centroids.
-
-        """
 
         self.topology = topology
         self.trajectory = trajectory
@@ -834,7 +832,6 @@ def plot(self, **kwargs):
         ylabel(r"$q_2$")
 
 
-@deprecate(new_name="Contacts", message="This class will be removed in 0.17")
 class ContactAnalysis1(object):
     """Perform a very flexible native contact analysis with respect to a single
     reference.
@@ -900,6 +897,7 @@ class ContactAnalysis1(object):
     .. deprecated:: 0.15.0
     """
 
+    @deprecate(new_name="Contacts", message="This class will be removed in 0.17")
     def __init__(self, *args, **kwargs):
         """Calculate native contacts within a group or between two groups.
 

package/MDAnalysis/analysis/diffusionmap.py

@@ -115,6 +115,7 @@
 map method. The :class:`DistanceMatrix` exists in
 :mod:`~MDAnalysis.analysis.diffusionmap` and can be passed
 as an initialization argument for :class:`DiffusionMap`.
+
     >>> import MDAnalysis as mda
     >>> import MDAnalysis.analysis.diffusionmap as diffusionmap
     >>> from MDAnalysis.tests.datafiles import PSF, DCD

package/MDAnalysis/analysis/gnm.py

@@ -24,7 +24,7 @@
 #Ben Hall ([email protected]) is to blame
 #Copyright 2011; Consider under GPL v2 or later
 
-"""
+r"""
 Elastic network analysis of MD trajectories --- :mod:`MDAnalysis.analysis.gnm`
 ==============================================================================
 
@@ -37,21 +37,22 @@
 
 An example is provided in the MDAnalysis Cookbook_, listed as GNMExample_.
 
-.. GNMExample_: https://github.com/MDAnalysis/MDAnalysisCookbook/blob/master/examples/GNMExample.py
-.. Cookbook_: https://github.com/MDAnalysis/MDAnalysisCookbook
+.. _GNMExample: https://github.com/MDAnalysis/MDAnalysisCookbook/blob/master/examples/GNMExample.py
+.. _Cookbook: https://github.com/MDAnalysis/MDAnalysisCookbook
 
 The basic approach is to pass a trajectory to :class:`GNMAnalysis` and then run
 the analysis::
 
-   u = MDAnalysis.Universe(PSF, DCD)
-   C = MDAnalysis.analysis.gnm.GNMAnalysis(u, ReportVector="output.txt")
+    u = MDAnalysis.Universe(PSF, DCD)
+    C = MDAnalysis.analysis.gnm.GNMAnalysis(u, ReportVector="output.txt")
+
+    C.run()
+    output = zip(*C.results)
 
-   C.run()
-   output = zip(*C.results)
+    with open("eigenvalues.dat", "w") as outputfile:
+        for item in output[1]:
+            outputfile.write(item + "\n")
 
-   with open("eigenvalues.dat", "w") as outputfile:
-      for item in output[1]:
-           outputfile.write(item + "\n")
 
 The results are found in :attr:`GNMAnalysis.results`, which can be
 used for further processing (see [Hall2007]_).
@@ -181,7 +182,10 @@ class GNMAnalysis(object):
           `Bonus_groups` is contained in `selection` as this could lead to
           double counting. No checks are applied. Default is ``None``.
 
-    .. SeeAlso:: :class:`closeContactGNMAnalysis`
+    See Also
+    --------
+    :class:`closeContactGNMAnalysis`
+
 
     .. versionchanged:: 0.16.0
        Made :meth:`generate_output` a private method :meth:`_generate_output`.
@@ -337,13 +341,18 @@ class closeContactGNMAnalysis(GNMAnalysis):
           the atoms that form a contact.
     MassWeight : bool (deprecated, optional)
           if set to ``True`` equivalent to `weights` set to "size".
-          .. Note:: This option does not perform a true mass weighting but
-                    weighting by the number of atoms in each residue; the name
-                    of the parameter exists for historical reasons and will
-                    be removed in 0.17.0. Until then, setting `MassWeight` to
-                    anything but ``None`` will override `weights`.
 
-    .. SeeAlso:: :class:`GNMAnalysis`
+    Notes
+    -----
+    The `MassWeight` option does not perform a true mass weighting but
+    weighting by the number of atoms in each residue; the name of the parameter
+    exists for historical reasons and will be removed in 0.17.0. Until then,
+    setting `MassWeight` to anything but ``None`` will override `weights`.
+
+    See Also
+    --------
+    :class:`GNMAnalysis`
+
 
     .. versionchanged:: 0.16.0
        Made :meth:`generate_output` a private method :meth:`_generate_output`.

package/MDAnalysis/analysis/hbonds/hbond_analysis.py

@@ -21,7 +21,7 @@
 #
 
 # Hydrogen Bonding Analysis
-"""
+r"""
 Hydrogen Bond analysis --- :mod:`MDAnalysis.analysis.hbonds.hbond_analysis`
 ===========================================================================
 
@@ -283,6 +283,7 @@ class HydrogenBondAnalysis_OtherFF(HydrogenBondAnalysis):
             ],
             ...
         ]
+
       The time of each step is not stored with each hydrogen bond frame but in
       :attr:`~HydrogenBondAnalysis.timesteps`.
 
@@ -467,7 +468,7 @@ def __init__(self, universe, selection1='protein', selection2='all', selection1_
 
         Parameters
         ----------
-        universe : universe
+        universe : Universe
             Universe object
         selection1 : str (optional)
             Selection string for first selection ['protein']
@@ -1019,14 +1020,15 @@ def generate_table(self):
           2. "acceptor_idx"
           3. "donor_index"
           4. "acceptor_index"
-          4. "donor_resnm"
-          5. "donor_resid"
-          6. "donor_atom"
-          7. "acceptor_resnm"
-          8. "acceptor_resid"
-          9. "acceptor_atom"
-          10. "distance"
-          11. "angle"
+          5. "donor_resnm"
+          6. "donor_resid"
+          7. "donor_atom"
+          8. "acceptor_resnm"
+          9. "acceptor_resid"
+          10. "acceptor_atom"
+          11. "distance"
+          12. "angle"
+
 
         .. _recsql: http://pypi.python.org/pypi/RecSQL
         """

package/MDAnalysis/analysis/leaflet.py

@@ -45,7 +45,7 @@
 (slow) heuristic method to find the best cut off for the LeafletFinder
 algorithm.
 
-.. MDAnalysisCookbook_: https://github.com/MDAnalysis/MDAnalysisCookbook/tree/master/examples
+.. _MDAnalysisCookbook: https://github.com/MDAnalysis/MDAnalysisCookbook/tree/master/examples
 
 
 Algorithm