Merge pull request #549 from jabooth/lmdocfixes

landmark module documentation fixes

docs/source/api/menpo/landmark/index.rst

@@ -23,8 +23,8 @@ Landmarks & Labeller
 .. toctree::
   :maxdepth: 1
 
-  LandmarkGroup
   LandmarkManager
+  LandmarkGroup
   labeller
 
 

menpo/landmark/base.py

@@ -83,14 +83,22 @@ def n_landmark_groups(self):
 
 
 class LandmarkManager(MutableMapping, Transformable):
-    """
-    Class for storing and manipulating Landmarks associated with an object.
-    This involves managing the internal dictionary, as well as providing
-    convenience functions for operations like viewing.
-
-    A LandmarkManager ensures that all it's Landmarks are of the
-    same dimensionality.
-
+    """Store for :map:`LandmarkGroup` instances associated with an object
+
+    Every :map:`Landmarkable` instance has an instance of this class available
+    at the ``.landmarks`` property.  It is through this class that all access
+    to landmarks attached to instances is handled. In general the
+    :map:`LandmarkManager` provides a dictionary-like interface for storing
+    landmarks. :map:`LandmarkGroup` instances are stored under string keys -
+    these keys are refereed to as the **group name**. A special case is
+    where there is a single unambiguous :map:`LandmarkGroup` attached to a
+    :map:`LandmarkManager` - in this case ``None`` can be used as a key to
+    access the sole group.
+
+
+    Note that all landmarks stored on a :map:`Landmarkable` in it's attached
+    :map:`LandmarkManager` are automatically transformed and copied with their
+    parent object.
     """
     def __init__(self):
         super(LandmarkManager, self).__init__()
@@ -274,7 +282,7 @@ def __str__(self):
 
 
 class LandmarkGroup(MutableMapping, Copyable, Viewable):
-    """
+    r"""
     An immutable object that holds a :map:`PointCloud` (or a subclass) and
     stores labels for each point. These labels are defined via masks on the
     :map:`PointCloud`. For this reason, the :map:`PointCloud` is considered to
@@ -285,13 +293,9 @@ class LandmarkGroup(MutableMapping, Copyable, Viewable):
 
     Parameters
     ----------
-    target : :map:`Landmarkable`
-        The parent object of this landmark group.
-    group : `str`
-        The label of the group.
     pointcloud : :map:`PointCloud`
         The pointcloud representing the landmarks.
-    labels_to_masks : `OrderedDict` of `str` to `bool` `ndarrays`
+    labels_to_masks : `ordereddict` {`str` -> `bool ndarray`}
         For each label, the mask that specifies the indices in to the
         pointcloud that belong to the label.
     copy : `bool`, optional
@@ -473,14 +477,13 @@ def n_dims(self):
         return self._pointcloud.n_dims
 
     def with_labels(self, labels=None):
-        """
-        Returns a new landmark group that contains only the given labels.
+        """A new landmark group that contains only the certain labels
 
         Parameters
         ----------
         labels : `str` or `list` of `str`, optional
             Labels that should be kept in the returned landmark group. If
-            None is passed, and if there is only one label on this group,
+            ``None`` is passed, and if there is only one label on this group,
             the label will be substituted automatically.
 
         Returns
@@ -502,14 +505,13 @@ def with_labels(self, labels=None):
         return self._new_group_with_only_labels(labels)
 
     def without_labels(self, labels):
-        """
-        Returns a new landmark group that contains all labels EXCEPT the given
+        """A new landmark group that excludes certain labels
         label.
 
         Parameters
         ----------
-        label : `str`
-            Label to exclude.
+        labels : `str` or `list` of `str`
+            Labels that should be excluded in the returned landmark group.
 
         Returns
         -------
@@ -571,9 +573,8 @@ def tojson(self):
 
         Returns
         -------
-        Dictionary with 'groups' key. Groups contains a landmark label set,
-        containing the label, spatial points and connectivity information.
-        Suitable or use in the by the `json` standard library package.
+        json : ``dict``
+            Dictionary conforming to the LJSON v2 specification.
         """
         labels = [{'mask': mask.nonzero()[0].tolist(),
                    'label': label}