Merge branch 'docstanya' into documentation

Lib/MV2.py

@@ -76,8 +76,13 @@ def _extractMetadata(a, axes=None, attributes=None,
 
 class var_unary_operation:
     def __init__(self, mafunc):
-        """ var_unary_operation(mafunc)
-        mafunc is an numpy.ma masked_unary_function.
+        """
+        Parameters
+        ----------
+               
+            var_unary_operation(mafunc)
+
+            mafunc is an numpy.ma masked_unary_function.
         """
         self.mafunc = mafunc
         self.__doc__ = mafunc.__doc__
@@ -91,8 +96,13 @@ def __call__(self, a, **kwargs):
 
 class var_unary_operation_with_axis:
     def __init__(self, mafunc):
-        """ var_unary_operation(mafunc)
-        mafunc is an numpy.ma masked_unary_function.
+        """ 
+        Parameters
+        ----------
+
+            var_unary_operation(mafunc)
+
+            mafunc is an numpy.ma masked_unary_function.
         """
         self.mafunc = mafunc
         self.__doc__ = mafunc.__doc__
@@ -108,14 +118,24 @@ def __call__(self, a, axis=0, **kwargs):
 
 
 def commonDomain(a, b, omit=None):
-    """commonDomain(a,b) tests that the domains of variables/arrays a and b are equal,
-    and returns the common domain if equal, or None if not equal.
+    """
+    Parameters
+    ----------
+
+        commonDomain(a,b)
+            tests that the domains of variables/arrays a and b are equal,
+            and 
 
-       The domains may differ in that one domain may have leading axes not common
-       to the other; the result domain will contain those axes.
+    Returns
+    -------
 
-       If <omit> is specified, as an integer i, skip comparison of the ith dimension
-       and return None for the ith (common) dimension.
+        the common domain if equal, or None if not equal.
+
+        The domains may differ in that one domain may have leading
+        axes not common to the other; the result domain will contain those axes.
+
+         If <omit> is specified, as an integer i, skip comparison of the ith dimension
+        and return None for the ith (common) dimension.
     """
 
     if isinstance(b, AbstractVariable):
@@ -126,8 +146,14 @@ def commonDomain(a, b, omit=None):
 
 
 def commonAxes(a, bdom, omit=None):
-    """Helper function for commonDomain. 'a' is a variable or array,
-    'b' is an axislist or None.
+    """Helper function for commonDomain. 
+
+    Parameters
+    ----------
+   
+        'a' is a variable or array,
+
+        'b' is an axislist or None.
     """
     if isinstance(a, AbstractVariable) and bdom is not None:
         adom = a.getAxisList()
@@ -181,9 +207,18 @@ def commonAxes(a, bdom, omit=None):
 
 
 def commonGrid(a, b, axes):
-    """commonGrid(a,b,axes) tests if the grids associated with variables a, b are equal,
-    and consistent with the list of axes. If so, the common grid is returned, else None
-    is returned. a and b can be numpy arrays, in which case the result is None.
+    """
+    Parameters
+    ----------
+
+        commonGrid(a,b,axes)
+
+            tests if the grids associated with variables a, b are equal
+            and consistent with the list of axes.
+ 
+        If so, the common grid is returned, else None is returned.
+
+        a and b can be numpy arrays, in which case the result is None.
 
         The common grid is 'consistent' with axes if the grid axes (e.g., the axes of
         latitude and longitude coordinate variables) are members of the list 'axes'.
@@ -232,8 +267,13 @@ def commonGrid1(a, gb, axes):
 
 class var_binary_operation:
     def __init__(self, mafunc):
-        """ var_binary_operation(mafunc)
-        mafunc is an numpy.ma masked_binary_function.
+        """
+        Parameters
+        ----------
+
+            var_binary_operation(mafunc)
+       
+            mafunc is an numpy.ma masked_binary_function.
         """
         self.mafunc = mafunc
         self.__doc__ = mafunc.__doc__
@@ -1015,7 +1055,12 @@ def reshape(a, newshape, axes=None, attributes=None, id=None, grid=None):
 
 
 def resize(a, new_shape, axes=None, attributes=None, id=None, grid=None):
-    """resize(a, new_shape) returns a new array with the specified shape.
+    """resize(a, new_shape) 
+
+    Returns
+    -------
+         a new array with the specified shape.
+
     The original array's total size can be any size."""
     ignore, attributes, id, ignore = _extractMetadata(a, axes, attributes, id)
     if axes is not None:
@@ -1031,9 +1076,13 @@ def resize(a, new_shape, axes=None, attributes=None, id=None, grid=None):
 
 def masked_array(a, mask=None, fill_value=None,
                  axes=None, attributes=None, id=None):
-    """masked_array(a, mask=None) =
-       array(a, mask=mask, copy=0, fill_value=fill_value)
-       Use fill_value(a) if None.
+    """
+    Parameters
+    ----------
+         masked_array(a, mask=None) =
+         array(a, mask=mask, copy=0, fill_value=fill_value)
+
+         Use fill_value(a) if None.
     """
     maresult = numpy.ma.masked_array(
         _makeMaskedArg(a),
@@ -1048,10 +1097,14 @@ def masked_array(a, mask=None, fill_value=None,
 def masked_values(data, value, rtol=1.e-5, atol=1.e-8, copy=1,
                   savespace=0, axes=None, attributes=None, id=None):
     """
-       masked_values(data, value, rtol=1.e-5, atol=1.e-8)
-       Create a masked array; mask is None if possible.
-       May share data values with original array, but not recommended.
-       Masked where abs(data-value)<= atol + rtol * abs(value)
+    Parameters
+    ----------
+    
+        masked_values(data, value, rtol=1.e-5, atol=1.e-8)
+
+        Create a masked array; mask is None if possible.
+        May share data values with original array, but not recommended.
+        Masked where abs(data-value)<= atol + rtol * abs(value)
     """
     maresult = numpy.ma.masked_values(_makeMaskedArg(
         data), value, rtol=rtol, atol=atol, copy=copy)
@@ -1078,8 +1131,13 @@ def isMaskedVariable(x):
 
 def set_default_fill_value(value_type, value):
     """Set the default fill value for value_type to value.
-    value_type is a string: 'real','complex','character','integer',or 'object'.
-    value should be a scalar or single-element array.
+    
+    Parameters
+    ----------
+        value_type is a string: 
+            'real','complex','character','integer',or 'object'.
+
+        value should be a scalar or single-element array.
     """
     if value_type == 'real':
         numpy.ma.default_real_fill_value = value
@@ -1099,8 +1157,15 @@ def fromfunction(f, dimensions):
 
 
 def diagonal(a, offset=0, axis1=0, axis2=1):
-    """diagonal(a, offset=0, axis1=0, axis2 = 1) returns the given
-       diagonals defined by the two dimensions of the array.
+    """
+    Parameters
+    ----------
+        diagonal(a, offset=0, axis1=0, axis2 = 1)
+
+    Returns
+    -------
+    
+        the given diagonals defined by the two dimensions of the array.
     """
     F = getattr(a, "fill_value", 1.e20)
     return TransientVariable(numpy.ma.diagonal(_makeMaskedArg(a),

Lib/avariable.py

@@ -177,8 +177,8 @@ def __call__(self, *args, **kwargs):
         """
         Selection of a subregion using selectors.
 
-        **Parameters:**
-
+        Parameters
+        ----------
             raw:
                 if set to 1, return numpy.ma only
             squeeze:
@@ -188,8 +188,8 @@ def __call__(self, *args, **kwargs):
             order:
                 if given, result is permuted into this order
 
-        **Returns:**
-
+        Returns
+        -------
              Subregion selected
         """
         # separate options from selector specs
@@ -429,12 +429,16 @@ def getConvention(self):
 # A child class may want to override this
     def getAxis(self, n):
         """Get the n-th axis.
+
         Parameters
         ----------
+
             n:
                Axis number
+
         Returns
         -------
+
             if n < 0: n = n + self.rank()
             self.getDomain()[n][0]"""
         if n < 0:
@@ -472,25 +476,24 @@ def hasCellData(self):
         return False
 
     def getAxisListIndex(self, axes=None, omit=None, order=None):
-        """Return a list of indices of axis objects;
-
-           Note
-           ----
-           If axes is **not** `None`, include only certain axes.
-           less the ones specified in omit.
+        """
+        Returns
+        -------
+            a list of indices of axis objects
 
-           If axes is `None`, use all axes of this variable.
+        Note
+        ----
+        If axes is **not** `None`, include only certain axes.
+        less the ones specified in omit.
 
-           Other specificiations are as for axisMatchIndex.
+        If axes is `None`, use all axes of this variable.
 
-        Returns
-        -------
-           a list of indices of axis objects;
+        Other specificiations are as for axisMatchIndex.
         """
         return axisMatchIndex(self.getAxisList(), axes, omit, order)
 
     def getAxisList(self, axes=None, omit=None, order=None):
-        """Get the list of axis objects;
+        """Get the list of axis objects
 
         Note
         ----
@@ -524,9 +527,10 @@ def getMissing(self, asarray=0):
                asarray :
                    '0' : scalar
                    '1' : numpy array
-           Return
-           ------
-               the missing value as a scalar, or as a numpy array if asarray==1"""
+
+           Returns
+           -------
+           the missing value as a scalar, or as a numpy array if asarray==1"""
 
         if hasattr(self, 'missing_value'):
             try:
@@ -695,16 +699,19 @@ def getLongitude(self):
     # Get an order string, such as "tzyx"
     def getOrder(self, ids=0):
         """
-        parameters
+        Parameters
         ----------
-             id:
-                 0 or 1
-        returns
+
+            id:
+                0 or 1
+
+        Returns
         -------
-            the order string, such as t, z, y, x (time, level, lat, lon).
+
+        the order string, such as t, z, y, x (time, level, lat, lon).
 
         Note
-        ----
+        
         * if ids == 0 (the default) for an axis that is not t,z,x,y
           the order string will contain a (-) character in that location.
           The result string will be of the same length as the number
@@ -1176,9 +1183,10 @@ def subRegion(self, *specs, **keys):
 
     def getValue(self, squeeze=1):
         """Get the entire set of values.
+
         Returns
         -------
-            All values and elimite the 1-D dimension.
+        All values and elimite the 1-D dimension.
         """
         return self.getSlice(Ellipsis, squeeze=squeeze)