added missing docs for new topology system (#363)

- added rst stubs for sphinx - updated rst docs (added links, reformatted, fixed, found out that Napoleon REQUIRES two lines before .. versionchanged/versionadded) - removed AtomGroup.rst TODO: - explain topology system and clean up core_modules.rst (work for @richardjgowers and @dotsdl)
MDAnalysis · Nov 18, 2016 · f0a282e · f0a282e
1 parent a294166
commit f0a282e
Show file tree

Hide file tree

Showing 16 changed files with 269 additions and 87 deletions.
diff --git a/package/MDAnalysis/core/groups.py b/package/MDAnalysis/core/groups.py
@@ -13,8 +13,48 @@
 # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787
 #
 
-"""Containers for objects in MDA
+"""\
+==========================================================
+Core objects: Containers --- :mod:`MDAnalysis.core.groups`
+==========================================================
 
+The :class:`~MDAnalysis.core.universe.Universe` instance contains all
+the particles in the system (which MDAnalysis calls
+:class:`Atom`). Groups of atoms are handled as :class:`AtomGroup`
+instances. The :class:`AtomGroup` is probably the most important
+object in MDAnalysis because virtually everything can be accessed
+through it. `AtomGroup` instances can be easily created (e.g., from a
+:meth:`AtomGroup.select_atoms` selection or just by slicing).
+
+For convenience, chemically meaningful groups of atoms such as a
+:class:`Residue` or a :class:`Segment` (typically a whole molecule or
+all of the solvent) also exist as containers, as well as groups of
+these units ((:class:`ResidueGroup`, :class:`SegmentGroup`).
+
+
+Classes
+=======
+
+Collections
+-----------
+
+.. autoclass:: AtomGroup
+   :members:
+.. autoclass:: ResidueGroup
+   :members:
+.. autoclass:: SegmentGroup
+   :members:
+
+
+Chemical units
+--------------
+
+.. autoclass:: Atom
+   :members:
+.. autoclass:: Residue
+   :members:
+.. autoclass:: Segment
+   :members:
 
 """
 from six.moves import zip
@@ -370,6 +410,7 @@ def bbox(self, **kwargs):
             2x3 array giving corners of bounding box as
             [[xmin, ymin, zmin], [xmax, ymax, zmax]].
 
+
         .. versionadded:: 0.7.2
         .. versionchanged:: 0.8 Added *pbc* keyword
         """
@@ -405,6 +446,7 @@ def bsphere(self, **kwargs):
         center : array
             Coordinates of sphere center as ``[xcen,ycen,zcen]``.
 
+
         .. versionadded:: 0.7.3
         .. versionchanged:: 0.8 Added *pbc* keyword
         """
@@ -490,9 +532,10 @@ def translate(self, t):
     def rotate(self, R, point=None):
         """Apply a rotation matrix `R` to the selection's coordinates.
 
-        No translation is done before the rotation is applied, so coordinates
-        are rotated about the origin. This differs from the behavior of
-        ``rotateby``.
+        By default (`point=None`) the rotation is performed around the
+        centroid of the group (:meth:`center_of_geometry`. In order to
+        perform a rotation around, say, the origin, use ``point=[0, 0,
+        0]``.
 
         Parameters
         ----------
@@ -606,6 +649,7 @@ def pack_into_box(self, box=None, inplace=True):
 
         Works with either orthogonal or triclinic box types.
 
+
         .. versionadded:: 0.8
 
         """
@@ -669,6 +713,7 @@ def wrap(self, compound="atoms", center="com", box=None):
         .. note::
            wrap with all default keywords is identical to :meth:`pack_into_box`
 
+
         .. versionadded:: 0.9.2
         """
         atomgroup = self.atoms.unique
@@ -1115,6 +1160,7 @@ def select_atoms(self, sel, *othersel, **selgroups):
                 therefore have atoms that were initially absent from the
                 instance :meth:`~select_atoms` was called from.
 
+
         .. versionchanged:: 0.7.4
            Added *resnum* selection.
         .. versionchanged:: 0.8.1
@@ -1138,6 +1184,7 @@ def split(self, level):
         ----------
         level : {'atom', 'residue', 'segment'}
 
+
         .. versionadded:: 0.9.0
         """
         accessors = {'segment': 'segindices',
@@ -1165,12 +1212,14 @@ def guess_bonds(self, vdwradii=None):
         vdwradii : dict, optional
           Dict relating atom type: vdw radii
 
+
         See Also
         --------
-        :func:`MDAnalysis.topology.core.guess_bonds` for details on the
-        algorithm used to guess bonds.
+        :func:`MDAnalysis.topology.guessers.guess_bonds`
+
 
         .. versionadded:: 0.10.0
+
         """
         from ..topology.core import guess_bonds, guess_angles, guess_dihedrals
         from .topologyattrs import Bonds, Angles, Dihedrals
@@ -1209,6 +1258,7 @@ def bond(self):
         ------
           `ValueError` if the AtomGroup is not length 2
 
+
         .. versionadded:: 0.11.0
         """
         if len(self) != 2:
@@ -1228,6 +1278,7 @@ def angle(self):
         ------
           `ValueError` if the AtomGroup is not length 3
 
+
         .. versionadded:: 0.11.0
         """
         if len(self) != 3:
@@ -1247,6 +1298,7 @@ def dihedral(self):
         ------
           `ValueError` if the AtomGroup is not length 4
 
+
         .. versionadded:: 0.11.0
         """
         if len(self) != 4:
@@ -1266,6 +1318,7 @@ def improper(self):
         ------
           `ValueError` if the AtomGroup is not length 4
 
+
         .. versionadded:: 0.11.0
         """
         if len(self) != 4:
@@ -1275,31 +1328,41 @@ def improper(self):
 
     def write(self, filename=None, file_format="PDB",
               filenamefmt="{trjname}_{frame}", **kwargs):
-        """Write AtomGroup to a file.
-
-        AtomGroup.write(filename[,format])
-
-        :Keywords:
-          *filename*
-               ``None``: create TRJNAME_FRAME.FORMAT from filenamefmt [``None``]
-          *format*
-                PDB, CRD, GRO, VMD (tcl), PyMol (pml), Gromacs (ndx) CHARMM (str)
-                Jmol (spt); case-insensitive and can also be supplied as the
-                filename extension [PDB]
-          *filenamefmt*
-                format string for default filename; use substitution tokens
-                'trjname' and 'frame' ["%(trjname)s_%(frame)d"]
-          *bonds*
-                how to handle bond information, especially relevant for PDBs;
-                default is ``"conect"``.
-                * ``"conect"``: write only the CONECT records defined in the original
-                  file
-                * ``"all"``: write out all bonds, both the original defined and those
-                  guessed by MDAnalysis
-                * ``None``: do not write out bonds
+        """Write `AtomGroup` to a file.
+
+        The output can either be a coordinate file or a selection, depending on
+        the `format`. Only single-frame coordinate files are supported. If you
+        need to write out a trajectory, see :mod:`MDAnalysis.coordinates`.
+
+        Parameters
+        ----------
+        filename : str, optional
+           ``None``: create TRJNAME_FRAME.FORMAT from filenamefmt [``None``]
+
+        format : str, optional
+            PDB, CRD, GRO, VMD (tcl), PyMol (pml), Gromacs (ndx) CHARMM (str)
+            Jmol (spt); case-insensitive and can also be supplied as the
+            filename extension [PDB]
+
+        filenamefmt : str, optional
+            format string for default filename; use substitution tokens
+            'trjname' and 'frame' ["%(trjname)s_%(frame)d"]
+
+        bonds : str, optional
+           how to handle bond information, especially relevant for PDBs;
+           default is ``"conect"``.
+
+           * ``"conect"``: write only the CONECT records defined in the original
+             file
+           * ``"all"``: write out all bonds, both the original defined and those
+             guessed by MDAnalysis
+           * ``None``: do not write out bonds
+
+
         .. versionchanged:: 0.9.0
            Merged with write_selection.  This method can now write both
            selections out.
+
         """
         import MDAnalysis.coordinates
         import MDAnalysis.selections

diff --git a/package/MDAnalysis/core/levels.py b/package/MDAnalysis/core/levels.py
@@ -14,23 +14,32 @@
 # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787
 #
 
-"""
+"""\
 Hierarchy levels --- :mod:`MDAnalysis.core.levels`
 ==================================================
 
-Levels are used to define the relationships between different containers in
-MDAnalysis
+:class:`Level` instances are used to define the relationships between
+different containers (see :mod:`MDAnalysis.core.groups`) in
+MDAnalysis.
+
+Levels can be navigated between using the :attr:`.child` and
+:attr:`.parent` attributes of the containers. Classes for containers
+at a given level are accessed using the :attr:`.singular` and
+:attr:`.plural` attributes::
+
+                     Level:
+           .singular =====================  .plural
+   Atom    <-        Atomlevel    ^ .child  ->  AtomGroup
+   Residue <-        Residuelevel !         ->  ResidueGroup
+   Segment <-        Segmentlevel v .parent ->  SegmentGroup
+
+.. SeeAlso::
+   :mod:`MDAnalysis.core.groups`
 
-Levels can be navigated between using the .child and .parent attributes
-Classes for containers at a given level are accessed using the .singular
-and .plural attributes
+.. autoclass:: Level
 
-                  Level:
-        .singular =====================  .plural
-Atom    <-        Atomlevel    ^ .child  ->  AtomGroup
-Residue <-        Residuelevel !         ->  ResidueGroup
-Segment <-        Segmentlevel v .parent ->  SegmentGroup
 """
+
 import functools
 
 
@@ -43,11 +52,14 @@ class Level(object):
 
     Can do comparisons with either
 
-    .singular gives the Class for Components of this Level
-    .plural gives the Class for Groups of this Level
+    - :attr:`.singular` gives the Class for Components of this Level
+    - :attr:`.plural` gives the Class for Groups of this Level
+
+    or
+
+    - :attr:`.parent` gives the :class:`Level` object above this
+    - :attr:`.child` gives the :class:`Level` object below this
 
-    .parent gives the Level object above this
-    .child gives the Level object below this
     """
     def __init__(self, name, singular, plural):
         self.name = name

diff --git a/package/MDAnalysis/core/selection.py b/package/MDAnalysis/core/selection.py
@@ -1,5 +1,5 @@
-# -*- Mode: python; tab-width: 4; indent-tabs-mode:nil; coding:utf-8 -*-
-# vim: tabstop=4 expandtab shiftwidth=4 softtabstop=4 
+# -*- Mode: python; tab-width: 4; indent-tabs-mode:nil; coding: utf-8 -*-
+# vim: tabstop=4 expandtab shiftwidth=4 softtabstop=4
 #
 # MDAnalysis --- http://www.MDAnalysis.org
 # Copyright (c) 2006-2015 Naveen Michaud-Agrawal, Elizabeth J. Denning, Oliver Beckstein
@@ -14,20 +14,22 @@
 # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787
 #
 
-
-"""
-Atom selection Hierarchy --- :mod:`MDAnalysis.core.selection`
+"""Atom selection Hierarchy --- :mod:`MDAnalysis.core.selection`
 =============================================================
 
-These objects are constructed and applied to the group
+This module contains objects that represent selections. They are
+constructed and then applied to the group.
 
-In general, Parser.parse() creates a Selection object
-from a selection string.
+In general, :meth:`Parser.parse` creates a :class:`Selection` object
+from a selection string. This :class:`Selection` object is then passed
+an :class:`~MDAnalysis.core.groups.AtomGroup` through its
+:meth:`~MDAnalysis.core.groups.AtomGroup.apply` method to apply the
+``Selection`` to the ``AtomGroup``.
 
-This Selection object is then passed an AtomGroup through its
-apply method to apply the Selection to the AtomGroup.
+This is all invisible to the user through the
+:meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` method of an
+:class:`~MDAnalysis.core.groups.AtomGroup`.
 
-This is all invisible to the user through ag.select_atoms
 """
 import six
 from six.moves import zip

diff --git a/package/MDAnalysis/core/topology.py b/package/MDAnalysis/core/topology.py
@@ -13,9 +13,39 @@
 # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787
 #
 
-"""
-Topology object --- :mod:`MDAnalysis.core.topology'
-===================================================================
+"""\
+Core Topology object --- :mod:`MDAnalysis.core.topology`
+========================================================
+
+.. versionadded:: 0.16.0
+
+:class:`Topology` is the core object that holds all topology information.
+
+TODO: Add in-depth discussion.
+
+Notes
+-----
+For developers: In MDAnalysis 0.16.0 this new topology system was
+introduced and discussed as issue `#363`_; this issue contains key
+information and discussions on the new system. The issue number *363*
+is also being used as a short-hand in discussions to refer to the new
+topology system.
+
+
+.. _`#363`: https://github.com/MDAnalysis/mdanalysis/issues/363
+
+Classes
+-------
+
+.. autoclass:: Topology
+   :members:
+.. autoclass:: TransTable
+   :members:
+
+Helper functions
+----------------
+
+.. autofunction:: make_downshift_arrays
 
 """
 
@@ -69,8 +99,10 @@ def make_downshift_arrays(upshift, nparents):
     Notes
     -----
     The final entry in the return array will be ``None`` to ensure that the
-    dtype of the array is object.  This means negative indexing should
-    not be used ever with these arrays.
+    dtype of the array is :class:`object`.
+
+    .. warning:: This means negative indexing should **never**
+                 be used with these arrays.
     """
     order = np.argsort(upshift)