First pass of documentation for the core module

zounds/core/axis.py

@@ -12,20 +12,34 @@ def __init__(self):
 
 class ArrayWithUnits(np.ndarray):
     """
-    Blah Blah Blah
+    `ArrayWithUnits` is an :class:`numpy.ndarray` subclass that allows for
+    indexing by more semantically meaningful slices.
+
+    It supports most methods on :class:`numpy.ndarray`, and makes a best-effort
+    to maintain meaningful dimensions throughout those operations.
 
     Args:
         arr (ndarray): The :class:`numpy.ndarray` instance containing the raw
-                       data for this instance
-        dimensions (iterable): iterable of :class:`Dimension`-derived classes
+            data for this instance
+        dimensions (list or tuple): list or tuple of :class:`Dimension`-derived
+            classes
+
+    Raises:
+        ValueError: when `arr.ndim` and `len(dimensions)` do not match
 
     Examples:
-        >>> print 'hai'
+        >>> from zounds import ArrayWithUnits, TimeDimension, Seconds, TimeSlice
+        >>> import numpy as np
+        >>> data = np.zeros(100)
+        >>> awu = ArrayWithUnits(data, [TimeDimension(Seconds(1))])
+        >>> sliced = awu[TimeSlice(Seconds(10))]
+        >>> sliced.shape
+        (10,)
 
     See Also:
         :class:`IdentityDimension`
-        :class:`zounds.timeseries.TimeDimension`
-        :class:`zounds.spectral.FrequencyDimension`
+        :class:`~zounds.timeseries.TimeDimension`
+        :class:`~zounds.spectral.FrequencyDimension`
     """
 
     def __new__(cls, arr, dimensions):

zounds/core/dimensions.py

@@ -1,7 +1,16 @@
 class Dimension(object):
     """
-    Class representing one dimension of a numpy array, making custom slices
-    (e.g., time spans or frequency bands) possible
+    Common base class representing one dimension of a numpy array.  Sub-classes
+    can define behavior making custom slices (e.g., time spans or
+    frequency bands) possible.
+
+    Implementors are primarily responsible for determining how custom slices
+    are transformed into integer indexes and slices that numpy can use directly.
+
+    See Also:
+        :class:`IdentityDimension`
+        :class:`~zounds.timeseries.TimeDimension`
+        :class:`~zounds.spectral.FrequencyDimension`
     """
 
     def __init__(self):
@@ -11,23 +20,44 @@ def modified_dimension(self, size, windowsize, stepsize=None):
         raise NotImplementedError()
 
     def metaslice(self, index, size):
+        """
+        Produce a new instance of this dimension, given a custom slice
+        """
         return self
 
     def integer_based_slice(self, index):
         """
-        Transforms a custom, user-defined slice into integer indices that numpy
-        can understand
+        Subclasses define behavior that transforms a custom, user-defined slice
+        into integer indices that numpy can understand
 
         Args:
             index (custom slice): A user-defined slice instance
         """
         raise NotImplementedError()
 
     def validate(self, size):
+        """
+        Subclasses check to ensure that the dimensions size does not validate
+        any assumptions made by this instance
+        """
         pass
 
 
 class IdentityDimension(Dimension):
+    """
+    A custom dimension that does not transform indices in any way, simply acting
+    as a pass-through.
+
+    Examples:
+        >>> from zounds import ArrayWithUnits, IdentityDimension
+        >>> import numpy as np
+        >>> data = np.zeros(100)
+        >>> arr = ArrayWithUnits(data, [IdentityDimension()])
+        >>> sliced = arr[4:6]
+        >>> sliced.shape
+        (2,)
+    """
+
     def __init__(self):
         super(IdentityDimension, self).__init__()