Merge pull request #132 from ycexiao/fix-docs

chore: fix docstrings to generate  API page.

Author: sbillinge

docs/source/conf.py

@@ -69,6 +69,16 @@
 # The master toctree document.
 master_doc = "index"
 
+napoleon_custom_sections = [
+    ("Managed Parameters", "Attributes"),
+    ("Usable Metadata", "Attributes"),
+    ("General Metadata", "Attributes"),
+    ("Metadata", "Attributes"),
+    ("Properties", "Attributes"),
+    ("Operator Attributes", "Attributes"),
+    ("Managed ParameterSets", "Attributes"),
+]
+
 # General information about the project.
 project = "diffpy.srfit"
 copyright = "%Y, The Trustees of Columbia University in the City of New York"

news/fix-docs.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* No news added: Fix docstrings manually.
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

src/diffpy/srfit/fitbase/fitcontribution.py

@@ -177,6 +177,7 @@ def addProfileGenerator(self, gen, name=None):
             A name for the calculator. If name is None (default), then
             the ProfileGenerator's name attribute will be used.
 
+
         Raises ValueError if the ProfileGenerator has no name.
         Raises ValueError if the ProfileGenerator has the same name as some
         other managed object.
@@ -220,6 +221,7 @@ def setEquation(self, eqstr, ns={}):
             A dictionary of Parameters, indexed by name, that are used
             in the eqstr, but not registered (default {}).
 
+
         Raises ValueError if ns uses a name that is already used for a
         variable.
         """
@@ -266,6 +268,7 @@ def setResidualEquation(self, eqstr):
             used, or the chi2 residual will be used if that does not
             exist.
 
+
         Two residuals are preset for convenience, "chiv" and "resv".
         chiv is defined such that dot(chiv, chiv) = chi^2.
         resv is defined such that dot(resv, resv) = Rw^2.

src/diffpy/srfit/fitbase/fitrecipe.py

@@ -187,6 +187,7 @@ def popFitHook(self, fithook=None, index=-1):
         index
             Index of FitHook instance to remove (default -1).
 
+
         Raises ValueError if fithook is not None, but is not present in the
         sequence.
         Raises IndexError if the sequence is empty or index is out of range.
@@ -214,6 +215,7 @@ def addContribution(self, con, weight=1.0):
         con
             The FitContribution to be stored.
 
+
         Raises ValueError if the FitContribution has no name
         Raises ValueError if the FitContribution has the same name as some
         other managed object.
@@ -236,6 +238,7 @@ def addParameterSet(self, parset):
         parset
             The ParameterSet to be stored.
 
+
         Raises ValueError if the ParameterSet has no name.
         Raises ValueError if the ParameterSet has the same name as some other
         managed object.
@@ -506,7 +509,12 @@ def addVar(
             A list of tags (default []). Both tag and tags can be
             applied.
 
-        Returns the ParameterProxy (variable) for the passed Parameter.
+
+        Returns
+        -------
+        vars
+            ParameterProxy (variable) for the passed Parameter.
+
 
         Raises ValueError if the name of the variable is already taken by
         another managed object.
@@ -549,6 +557,7 @@ def delVar(self, var):
         var
             A variable of the FitRecipe.
 
+
         Raises ValueError if var is not part of the FitRecipe.
         """
 
@@ -592,6 +601,7 @@ def newVar(self, name, value=None, fixed=False, tag=None, tags=[]):
             A list of tags (default []). Both tag and tags can be
             applied.
 
+
         Returns the new variable (Parameter instance).
         """
         # This will fix the Parameter
@@ -798,6 +808,7 @@ def constrain(self, par, con, ns={}):
             A dictionary of Parameters, indexed by name, that are used
             in the eqstr, but not part of this object (default {}).
 
+
         Raises ValueError if ns uses a name that is already used for a
         variable.
         Raises ValueError if eqstr depends on a Parameter that is not part of

src/diffpy/srfit/fitbase/fitresults.py

@@ -90,6 +90,7 @@ class FitResults(object):
         The derivatives of the constraint equations with respect to
         the variables. This is used internally.
 
+
     Each of these attributes, except the recipe, are created or updated when
     the update method is called.
     """
@@ -338,7 +339,10 @@ def formatResults(self, header="", footer="", update=False):
         update
             Flag indicating whether to call update() (default False).
 
-        Returns a string containing the formatted results.
+        Returns
+        -------
+        out
+            a string containing the formatted results.
         """
         if update:
             self.update()
@@ -515,7 +519,7 @@ def formatResults(self, header="", footer="", update=False):
     def printResults(self, header="", footer="", update=False):
         """Format and print the results.
 
-        Attributes
+        Parameters
         ----------
         header
             A header to add to the output (default "")
@@ -533,8 +537,10 @@ def __str__(self):
     def saveResults(self, filename, header="", footer="", update=False):
         """Format and save the results.
 
-        filename -  Name of the save file.
+        Parameters
         ----------------------------------
+        filename
+            Name of the save file.
         header
             A header to add to the output (default "")
         footer

src/diffpy/srfit/fitbase/parameter.py

@@ -72,6 +72,7 @@ def __init__(self, name, value=None, const=False):
             A flag inticating whether the Parameter is a constant (like
             pi).
 
+
         Raises ValueError if the name is not a valid attribute identifier
         """
         self.constrained = False
@@ -94,7 +95,10 @@ def setValue(self, val):
             The upper bounds for the bounds list. If this is None
             (default), then the upper bound will not be alterered.
 
-        Returns self so that mutators can be chained.
+        Returns
+        -------
+        self
+            Returns self so that mutators can be chained.
         """
         Argument.setValue(self, val)
         return self
@@ -112,7 +116,10 @@ def setConst(self, const=True, value=None):
             is not None, then the parameter will get a new value,
             constant or otherwise.
 
-        Returns self so that mutators can be chained.
+        Returns
+        -------
+        self
+            Returns self so that mutators can be chained.
         """
         self.const = bool(const)
         if value is not None:
@@ -129,7 +136,10 @@ def boundRange(self, lb=None, ub=None):
         ub
             The upper bound for the bounds list.
 
-        Returns self so that mutators can be chained.
+        Returns
+        -------
+        self
+            Returns self so that mutators can be chained.
         """
         if lb is not None:
             self.bounds[0] = lb
@@ -150,7 +160,10 @@ def boundWindow(self, lr=0, ur=None):
             value + ur. If this is None (default), then the value of the
             lower radius is used.
 
-        Returns self so that mutators can be chained.
+        Returns
+        -------
+        self
+            Returns self so that mutators can be chained.
         """
         val = self.getValue()
         lb = val - lr
@@ -199,6 +212,7 @@ def __init__(self, name, par):
         par
             The Parameter this is a proxy for.
 
+
         Raises ValueError if the name is not a valid attribute identifier
         """
         validateName(name)
@@ -312,6 +326,7 @@ def __init__(self, name, obj, getter=None, setter=None, attr=None):
             parameter. If attr is None (default), then both getter and
             setter must be specified.
 
+
         Raises ValueError if exactly one of getter or setter is not None, or if
         getter, setter and attr are all None.
         """

src/diffpy/srfit/fitbase/parameterset.py

@@ -95,6 +95,7 @@ def addParameterSet(self, parset):
         parset
             The ParameterSet to be stored.
 
+
         Raises ValueError if the ParameterSet has no name.
         Raises ValueError if the ParameterSet has the same name as some other
         managed object.

src/diffpy/srfit/fitbase/profile.py

@@ -319,7 +319,14 @@ def loadtxt(self, *args, **kw):
         Raises ValueError if the call to numpy.loadtxt returns fewer
         than 2 arrays.
 
-        Returns the x, y and dy arrays loaded from the file
+        Returns
+        -------
+        x
+            x array loaded from the file.
+        y
+            y array loaded from the file.
+        dy
+            dy array loaded from the file.
         """
         if len(args) == 8 and not args[-1]:
             args = list(args)
@@ -423,9 +430,13 @@ def rebinArray(A, xold, xnew):
     xnew
         New sampling array
 
+
     This uses cubic spline interpolation.
 
-    Returns: A new array over the new sampling array.
+    Returns
+    -------
+    array
+        A new array over the new sampling array.
     """
     if numpy.array_equal(xold, xnew):
         return A

src/diffpy/srfit/fitbase/profilegenerator.py

@@ -20,14 +20,23 @@
 
 To define a ProfileGenerator, one must implement the required Parameters
 and ParameterSets as well as overload the __call__ method with the
-calculation. A very simple example is > class
-Gaussian(ProfileGenerator): > >    def __init__(self): >        #
-Initialize and give this a name >        ProfileGenerator.__init__(self,
-"g") >        # Add amplitude, center and width parameters >
-self.newParameter("amp", 0) >        self.newParameter("center", 0) >
-self.newParameter("width", 0) > >    def __call__(self, x): >        a =
-self.amp.getValue() >        x0 = self.center.getValue() >        w =
-self.width.getValue() >        return a * exp(-0.5*((x-x0)/w)**2)
+calculation. A very simple example is
+
+.. code:: python
+
+    class Gaussian(ProfileGenerator):
+        def __init__(self):
+            # Initialize and give this a name
+            ProfileGenerator.__init__(self, "g")
+            # Add amplitude, center and width parameters
+            self.newParameter("amp", 0)
+            self.newParameter("center", 0)
+            self.newParameter("width", 0)
+        def __call__(self, x):
+            a = self.amp.getValue()
+            x0 = self.center.getValue()
+            w = self.width.getValue()
+            return a * exp(-0.5*((x-x0)/w)**2)
 
 More examples can be found in the example directory of the
 documentation.

src/diffpy/srfit/fitbase/profileparser.py

@@ -29,8 +29,6 @@
 class ProfileParser(object):
     """Class for parsing data from a or string.
 
-    Attributes
-
     Attributes
     ----------
     _format
@@ -41,20 +39,20 @@ class ProfileParser(object):
         The data from each bank. Each bank contains a (x, y, dx,
         dy)
         tuple:
-                    x
-        A numpy array containing the independent
-        variable read from the file.
-                    y
-        A numpy array containing the profile
-        from the file.
-                    dx
-        A numpy array containing the uncertainty in x
-        read from the file. This is None if the
-        uncertainty cannot be read.
-                    dy
-        A numpy array containing the uncertainty read
-        from the file. This is None if the uncertainty
-        cannot be read.
+        x
+            A numpy array containing the independent
+            variable read from the file.
+        y
+            A numpy array containing the profile
+            from the file.
+        dx
+            A numpy array containing the uncertainty in x
+            read from the file. This is None if the
+            uncertainty cannot be read.
+        dy
+            A numpy array containing the uncertainty read
+            from the file. This is None if the uncertainty
+            cannot be read.
     _x
         Independent variable from the chosen bank
     _y
@@ -66,10 +64,9 @@ class ProfileParser(object):
     _meta
         A dictionary containing metadata read from the file.
 
-    General Metadata
 
-    Attributes
-    ----------
+    General Metadata
+    ----------------
     filename
         The name of the file from which data was parsed. This key
         will not exist if data was not read from file.