fix: use numpy-style docstring

Author: ycexiao

CHANGELOG.rst

@@ -9,7 +9,7 @@ Release notes
 
 
 Version 3.0.0 – 2019-03-14
-==========================
+--------------------------
 
 **Added:**
 

news/fix-docstring.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* No news added: Fix the docstring in this repo
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

src/diffpy/srfit/equation/builder.py

@@ -109,12 +109,17 @@
 class EquationFactory(object):
     """A Factory for equations.
 
-    builders    --  A dictionary of BaseBuilders registered with the
-                    factory, indexed by name.
-    newargs     --  A set of new arguments created by makeEquation. This is
-                    redefined whenever makeEquation is called.
-    equations   --  Set of equations that have been built by the
-                    EquationFactory.
+    Attributes
+    ----------
+    builders
+        A dictionary of BaseBuilders registered with the
+        factory, indexed by name.
+    newargs
+        A set of new arguments created by makeEquation. This is
+        redefined whenever makeEquation is called.
+    equations
+        Set of equations that have been built by the
+        EquationFactory.
     """
 
     symbols = ("+", "-", "*", "/", "**", "%", "|")
@@ -138,20 +143,25 @@ def makeEquation(
         """Make an equation from an equation string.
 
         Arguments
-        eqstr       --  An equation in string form using standard python
-                        syntax.  The equation string can use any function
-                        registered literal or function, including numpy ufuncs
-                        that are automatically registered.
-        buildargs   --  A flag indicating whether missing arguments can be
-                        created by the Factory (default True). If False, then
-                        the a ValueError will be raised if there are undefined
-                        arguments in the eqstr. Built arguments will be of type
-                        argclass.
-        argclass    --  Class to use when creating new Arguments (default
-                        diffpy.srfit.equation.literals.Argument). The class
-                        constructor must accept the 'name' key word.
-        argkw       --  Key word dictionary to pass to the argclass constructor
-                        (default {}).
+        ---------
+        eqstr
+            An equation in string form using standard python
+            syntax.  The equation string can use any function
+            registered literal or function, including numpy ufuncs
+            that are automatically registered.
+        buildargs
+            A flag indicating whether missing arguments can be
+            created by the Factory (default True). If False, then
+            the a ValueError will be raised if there are undefined
+            arguments in the eqstr. Built arguments will be of type
+            argclass.
+        argclass
+            Class to use when creating new Arguments (default
+            diffpy.srfit.equation.literals.Argument). The class
+            constructor must accept the 'name' key word.
+        argkw
+            Key word dictionary to pass to the argclass constructor
+            (default {}).
 
         Returns a callable Literal representing the equation string.
         """
@@ -202,11 +212,16 @@ def registerFunction(self, name, func, argnames):
 
         This will register a builder for the function.
 
-        name    --  The name of the function
-        func    --  A callable python object
-        argnames--  The argument names for func. If these names do not
-                    correspond to builders, then new constants with value 0
-                    will be created for each name.
+        Attributes
+        ----------
+        name
+            The name of the function
+        func
+            A callable python object
+        argnames
+            The argument names for func. If these names do not
+            correspond to builders, then new constants with value 0
+            will be created for each name.
 
         Returns the registered builder.
         """
@@ -294,16 +309,21 @@ def _prepareBuilders(self, eqstr, buildargs, argclass, argkw):
         rebuilds the newargs attribute.
 
         Arguments
-        eqstr       --  An equation in string as specified in the makeEquation
-                        method.
-        buildargs   --  A flag indicating whether missing arguments can be
-                        created by the factory. If False, then the a ValueError
-                        will be raised if there are undefined arguments in the
-                        eqstr.
-        argclass    --  Class to use when creating new Arguments. The class
-                        constructor must accept the 'name' key word.
-        argkw       --  Key word dictionary to pass to the argclass
-                        constructor.
+        ---------
+        eqstr
+            An equation in string as specified in the makeEquation
+            method.
+        buildargs
+            A flag indicating whether missing arguments can be
+            created by the factory. If False, then the a ValueError
+            will be raised if there are undefined arguments in the
+            eqstr.
+        argclass
+            Class to use when creating new Arguments. The class
+            constructor must accept the 'name' key word.
+        argkw
+            Key word dictionary to pass to the argclass
+            constructor.
 
         Raises ValueError if new arguments must be created, but this is
         disallowed due to the buildargs flag.
@@ -392,7 +412,9 @@ class BaseBuilder(object):
     arguments can be other BaseBuilder instances or constants.
 
     Attributes
-    literal     --  The equation Literal being built by this instance.
+    ----------
+    literal
+        The equation Literal being built by this instance.
     """
 
     def __init__(self):
@@ -424,8 +446,11 @@ def __evalBinary(self, other, OperatorClass, onleft=True):
 
         Other can be an BaseBuilder or a constant.
 
-        onleft  --  Indicates that the operator was passed on the left side
-                    (default True).
+        Attributes
+        ----------
+        onleft
+            Indicates that the operator was passed on the left side
+            (default True).
         """
         # Create the Operator
         op = OperatorClass()
@@ -520,20 +545,27 @@ class ArgumentBuilder(BaseBuilder):
     arguments can be other BaseBuilder instances or constants.
 
     Attributes
-    literal     --  The Argument wrapped by this instance.
+    ----------
+    literal
+        The Argument wrapped by this instance.
     """
 
     def __init__(self, value=None, name=None, const=False, arg=None):
         """Create an ArgumentBuilder instance, containing a new Argument.
 
         Arguments
-        value   --  The value of the wrapped Argument (float, default None)
-        name    --  The name of the wrapped Argument (string, default None)
-        const   --  Flag indicating whether the Argument is constant (bool,
-                    default False)
-        arg     --  A pre-defined Argument to use. If this is None (default),
-                    then a new Argument will be created from value, name and
-                    const.
+        ---------
+        value
+            The value of the wrapped Argument (float, default None)
+        name
+            The name of the wrapped Argument (string, default None)
+        const
+            Flag indicating whether the Argument is constant (bool,
+            default False)
+        arg
+            A pre-defined Argument to use. If this is None (default),
+            then a new Argument will be created from value, name and
+            const.
         """
         BaseBuilder.__init__(self)
         if arg is None:
@@ -552,19 +584,25 @@ class OperatorBuilder(BaseBuilder):
     """BaseBuilder wrapper around an Operator literal.
 
     Attributes
-    literal     --  The Operator wrapped by this instance.
-    name        --  The name of the operator to be wrapped
+    ----------
+    literal
+        The Operator wrapped by this instance.
+    name
+        The name of the operator to be wrapped
     """
 
     def __init__(self, name, op=None):
         """Wrap an Operator or a function by name.
 
         Arguments
-        name    --  The name of the wrapped Operator
-        op      --  If specified, this sets the literal attribute as this
-                    operator (default None). Otherwise, the name is assumed to
-                    be that of a numpy ufunc, which is used to specify the
-                    Operator.
+        ---------
+        name
+            The name of the wrapped Operator
+        op
+            If specified, this sets the literal attribute as this
+            operator (default None). Otherwise, the name is assumed to
+            be that of a numpy ufunc, which is used to specify the
+            Operator.
         """
         BaseBuilder.__init__(self)
         self.name = name
@@ -576,7 +614,10 @@ def __call__(self, *args):
 
         This creates a new builder that encapsulates the operation.
 
-        args    --  Arguments of the operation.
+        Attributes
+        ----------
+        args
+            Arguments of the operation.
 
         Raises ValueError if self.literal.nin >= 0 and len(args) != op.nin
         """
@@ -637,10 +678,16 @@ def wrapOperator(name, op):
 def wrapFunction(name, func, nin=2, nout=1):
     """Wrap a function in an OperatorBuilder instance.
 
-    name    --  The name of the function
-    func    --  A callable python object
-    nin     --  The number of input arguments (default 2)
-    nout    --  The number of return values (default 1)
+    Attributes
+    ----------
+    name
+        The name of the function
+    func
+        A callable python object
+    nin
+        The number of input arguments (default 2)
+    nout
+        The number of return values (default 1)
 
     Returns the OperatorBuilder instance that wraps the function.
     """
@@ -661,7 +708,8 @@ def getBuilder(name):
 
 def __wrapNumpyOperators():
     """Export all numpy operators as OperatorBuilder instances in the module
-    namespace."""
+    namespace.
+    """
     for name in dir(numpy):
         op = getattr(numpy, name)
         if isinstance(op, numpy.ufunc):
@@ -676,7 +724,8 @@ def __wrapNumpyOperators():
 def __wrapSrFitOperators():
     """Export all non-base operators from the
     diffpy.srfit.equation.literals.operators module as OperatorBuilder
-    instances in the module namespace."""
+    instances in the module namespace.
+    """
     opmod = literals.operators
     excluded_types = set((opmod.CustomOperator, opmod.UFuncOperator))
 

src/diffpy/srfit/equation/equationmod.py

@@ -56,19 +56,32 @@ class Equation(Operator):
     accepts new argument values for the literal tree.
 
     Attributes
-    root    --  The root Literal of the equation tree
-    argdict --  An OrderedDict of Arguments from the root.
-    args    --  Property that gets the values of argdict.
+    ----------
+    root
+        The root Literal of the equation tree
+    argdict
+        An OrderedDict of Arguments from the root.
+    args
+        Property that gets the values of argdict.
 
     Operator Attributes
-    args    --  List of Literal arguments, set with 'addLiteral'
-    name    --  A name for this operator. e.g. "add" or "sin"
-    nin     --  Number of inputs (<1 means this is variable)
-    nout    --  Number of outputs
-    operation   --  Function that performs the operation. e.g. numpy.add.
-    symbol  --  The symbolic representation. e.g. "+" or "sin".
-    _value  --  The value of the Operator.
-    value   --  Property for 'getValue'.
+    -------------------
+    args
+        List of Literal arguments, set with 'addLiteral'
+    name
+        A name for this operator. e.g. "add" or "sin"
+    nin
+        Number of inputs (<1 means this is variable)
+    nout
+        Number of outputs
+    operation
+        Function that performs the operation. e.g. numpy.add.
+    symbol
+        The symbolic representation. e.g. "+" or "sin".
+    _value
+        The value of the Operator.
+    value
+        Property for 'getValue'.
     """
 
     # define abstract attributes from the Operator base.
@@ -78,10 +91,14 @@ class Equation(Operator):
     def __init__(self, name=None, root=None):
         """Initialize.
 
-        name    --  A name for this Equation.
-        root    --  The root node of the Literal tree (default None). If root
-                    is not passed here, you must call the 'setRoot' method to
-                    set or change the root node.
+        Attributes
+        ----------
+        name
+            A name for this Equation.
+        root
+            The root node of the Literal tree (default None). If root
+            is not passed here, you must call the 'setRoot' method to
+            set or change the root node.
         """
         # Operator stuff. We circumvent Operator.__init__ since we're using
         # args as a property. We cannot set it, as the Operator tries to do.
@@ -127,7 +144,7 @@ def __getattr__(self, name):
     )
 
     def __dir__(self):
-        "Return sorted list of attributes for this object."
+        """Return sorted list of attributes for this object."""
         rv = set(dir(type(self)))
         rv.update(self.__dict__, self.argdict)
         rv = sorted(rv)