docs: use numpy docstring in .py files

Author: ycexiao

news/fix-docstring.rst

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

src/diffpy/srreal/atomradiitable.py

@@ -35,7 +35,10 @@ class CovalentRadiiTable(AtomRadiiTable):
     def _standardLookup(self, smbl):
         """Return covalent atom radius in Angstroms.
 
-        smbl -- string symbol of an element
+        Attributes
+        ----------
+        smbl
+            string symbol of an element
 
         Return float.  Raise ValueError for unknown element symbol.
         """

src/diffpy/srreal/bondcalculator.py

@@ -58,9 +58,13 @@ def _init_kwargs(self, **kwargs):
 def _call_kwargs(self, structure=None, **kwargs):
     """Return sorted bond distances in the specified structure.
 
-    structure    -- structure to be evaluated, an instance of diffpy Structure
-                    or pyobjcryst Crystal.  Reuse the last structure when None.
-    kwargs       -- optional parameter settings for this calculator
+    Attributes
+    ----------
+    structure
+        structure to be evaluated, an instance of diffpy Structure
+        or pyobjcryst Crystal.  Reuse the last structure when None.
+    kwargs
+        optional parameter settings for this calculator
 
     Return a sorted numpy array.
     """

src/diffpy/srreal/bvscalculator.py

@@ -75,9 +75,13 @@ def _init_kwargs(self, **kwargs):
 def _call_kwargs(self, structure=None, **kwargs):
     """Return bond valence sums at each atom site in the structure.
 
-    structure    -- structure to be evaluated, an instance of diffpy Structure
-                    or pyobjcryst Crystal.  Reuse the last structure when None.
-    kwargs       -- optional parameter settings for this calculator
+    Attributes
+    ----------
+    structure
+        structure to be evaluated, an instance of diffpy Structure
+        or pyobjcryst Crystal.  Reuse the last structure when None.
+    kwargs
+        optional parameter settings for this calculator
 
     Return an array of calculated valence sums.
     See valences for the expected values.

src/diffpy/srreal/devutils/tunePeakPrecision.py

@@ -54,7 +54,10 @@
 def Gpdffit2(qmax):
     """Calculate reference nickel PDF using diffpy.pdffit2.
 
-    qmax    -- vawevector cutoff value in 1/A
+    Attributes
+    ----------
+    qmax
+        vawevector cutoff value in 1/A
 
     Return numpy array of (r, g).
     """
@@ -70,9 +73,13 @@ def Gpdffit2(qmax):
 def Gsrreal(qmax, peakprecision=None):
     """Calculate nickel PDF using PDFCalculator from diffpy.srreal.
 
-    qmax            -- vawevector cutoff value in 1/A
-    peakprecision   -- precision factor affecting peak cutoff,
-                       keep at default value when None.
+    Attributes
+    ----------
+    qmax
+        vawevector cutoff value in 1/A
+    peakprecision
+        precision factor affecting peak cutoff,
+        keep at default value when None.
 
     Return numpy array of (r, g).
     """
@@ -91,19 +98,30 @@ def Gsrreal(qmax, peakprecision=None):
 def comparePDFCalculators(qmax, peakprecision=None):
     """Compare Ni PDF calculations with pdffit2 and PDFCalculator.
 
-    qmax            -- vawevector cutoff value in 1/A
-    peakprecision   -- precision factor affecting peak cutoff,
-                       keep at default value when None.
+    Attributes
+    ----------
+    qmax
+        vawevector cutoff value in 1/A
+    peakprecision
+        precision factor affecting peak cutoff,
+        keep at default value when None.
 
     Return a dictionary of benchmark results with the following keys:
 
-    qmax    -- vawevector cutoff value
-    peakprecision -- actual peak precision used in PDFCalculator
-    r       -- common r-grid for the PDF arrays
-    g0, g1  -- calculated PDF curves from pdffit2 and PDFCalculator
-    gdiff   -- PDF difference equal (g0 - g1)
-    grmsd   -- root mean square value of PDF curves difference
-    t0, t1  -- CPU times used by pdffit2 and PDFCalculator calls
+    Attributes
+    ----------
+    qmax
+        vawevector cutoff value
+    peakprecision
+        actual peak precision used in PDFCalculator
+    r
+        common r-grid for the PDF arrays
+        g0, g1  -- calculated PDF curves from pdffit2 and PDFCalculator
+    gdiff
+        PDF difference equal (g0 - g1)
+    grmsd
+        root mean square value of PDF curves difference
+        t0, t1  -- CPU times used by pdffit2 and PDFCalculator calls
     """
     rv = {}
     rv["qmax"] = qmax
@@ -147,7 +165,10 @@ def processCommandLineArguments():
 def plotComparison(cmpdata):
     """Plot comparison of PDF curves.
 
-    cmpdata -- dictionary returned from comparePDFCalculators
+    Attributes
+    ----------
+    cmpdata
+        dictionary returned from comparePDFCalculators
 
     No return value.
     """

src/diffpy/srreal/overlapcalculator.py

@@ -66,9 +66,13 @@ def _init_kwargs(self, **kwargs):
 def _call_kwargs(self, structure=None, **kwargs):
     """Return siteSquareOverlaps per each site of the structure.
 
-    structure    -- structure to be evaluated, an instance of diffpy Structure
-                    or pyobjcryst Crystal.  Reuse the last structure when None.
-    kwargs       -- optional parameter settings for this calculator
+    Attributes
+    ----------
+    structure
+        structure to be evaluated, an instance of diffpy Structure
+        or pyobjcryst Crystal.  Reuse the last structure when None.
+    kwargs
+        optional parameter settings for this calculator
 
     Return a numpy array.
     """

src/diffpy/srreal/parallel.py

@@ -31,9 +31,14 @@
 def createParallelCalculator(pqobj, ncpu, pmap):
     """Create a proxy parallel calculator to a PairQuantity instance.
 
-    pqobj    -- instance of PairQuantity calculator to be run in parallel
-    ncpu     -- number of parallel jobs
-    pmap     -- a parallel map function used to submit job to workers
+    Attributes
+    ----------
+    pqobj
+        instance of PairQuantity calculator to be run in parallel
+    ncpu
+        number of parallel jobs
+    pmap
+        a parallel map function used to submit job to workers
 
     The ``pqobj.evaluatortype`` is reset to 'BASIC' because other
     evaluator types are not supported within parallel calculations.
@@ -48,18 +53,28 @@ class to the wrapper PairQuantity type with the same interface.
 
         Instance data:
 
-        pqobj    -- the master PairQuantity object to be evaluated in parallel
-        ncpu     -- number of parallel jobs
-        pmap     -- a parallel map function used to submit job to workers
+        Attributes
+        ----------
+        pqobj
+            the master PairQuantity object to be evaluated in parallel
+        ncpu
+            number of parallel jobs
+        pmap
+            a parallel map function used to submit job to workers
         """
 
         def __init__(self, pqobj, ncpu, pmap):
             """Initialize a parallel proxy to the PairQuantity instance.
 
-            pqobj    -- instance of PairQuantity calculator to be run
-                        in parallel
-            ncpu     -- number of parallel jobs
-            pmap     -- a parallel map function used to submit job to workers
+            Attributes
+            ----------
+            pqobj
+                instance of PairQuantity calculator to be run
+                in parallel
+            ncpu
+                number of parallel jobs
+            pmap
+                a parallel map function used to submit job to workers
             """
             # use explicit assignment to avoid setattr forwarding to the pqobj
             object.__setattr__(self, "pqobj", pqobj)
@@ -73,9 +88,12 @@ def eval(self, stru=None):
             """Perform parallel calculation and return internal value
             array.
 
-            stru -- object that can be converted to StructureAdapter,
-                    e.g., example diffpy Structure or pyobjcryst Crystal.
-                    Use the last structure when None.
+            Attributes
+            ----------
+            stru
+                object that can be converted to StructureAdapter,
+                e.g., example diffpy Structure or pyobjcryst Crystal.
+                Use the last structure when None.
 
             Return numpy array.
             """

src/diffpy/srreal/pdfbaseline.py

@@ -52,21 +52,27 @@ def makePDFBaseline(name, fnc, replace=False, **dbattrs):
     This is required for using Python function as
     PDFCalculator.baseline.
 
-    name     -- unique string name for registering Python function in the
-                global registry of PDFBaseline types.  This will be the
-                string identifier for the createByType factory.
-    fnc      -- Python function of a floating point argument and optional
-                float parameters.  The parameters need to be registered as
-                double attributes in the functor class.  The function fnc
-                must be picklable and it must return a float.
-    replace  -- when set replace any PDFBaseline type already registered
-                under the name.  Otherwise raise RuntimeError when the
-                name is taken.
-    dbattrs  -- optional float parameters of the wrapped function.
-                These will be registered as double attributes in the
-                functor class.  The wrapped function must be callable as
-                fnc(x, **dbattrs).  Make sure to pick attribute names that
-                do not conflict with other PDFCalculator attributes.
+    Attributes
+    ----------
+    name
+        unique string name for registering Python function in the
+        global registry of PDFBaseline types.  This will be the
+        string identifier for the createByType factory.
+    fnc
+        Python function of a floating point argument and optional
+        float parameters.  The parameters need to be registered as
+        double attributes in the functor class.  The function fnc
+        must be picklable and it must return a float.
+    replace
+        when set replace any PDFBaseline type already registered
+        under the name.  Otherwise raise RuntimeError when the
+        name is taken.
+    dbattrs
+        optional float parameters of the wrapped function.
+        These will be registered as double attributes in the
+        functor class.  The wrapped function must be callable as
+        fnc(x, **dbattrs).  Make sure to pick attribute names that
+        do not conflict with other PDFCalculator attributes.
 
     Return an instance of the new PDFBaseline class.
 

src/diffpy/srreal/pdfcalculator.py

@@ -167,9 +167,13 @@ def _call_kwargs(self, structure=None, **kwargs):
         attributes, these override any properties that may be passed
         from the structure, such as spdiameter.
 
-        structure    -- a structure object to be evaluated.  Reuse the last
-                        structure when None.
-        kwargs       -- optional parameter settings for this calculator
+        Attributes
+        ----------
+        structure
+            a structure object to be evaluated.  Reuse the last
+            structure when None.
+        kwargs
+            optional parameter settings for this calculator
 
         Example:    pdfcalc(structure, qmax=20, spdiameter=15)
 

src/diffpy/srreal/pdfenvelope.py

@@ -81,21 +81,27 @@ def makePDFEnvelope(name, fnc, replace=False, **dbattrs):
     This is required for using Python function as PDFCalculator
     envelope.
 
-    name     -- unique string name for registering Python function in the
-                global registry of PDFEnvelope types.  This will be the
-                string identifier for the createByType factory.
-    fnc      -- Python function of a floating point argument and optional
-                float parameters.  The parameters need to be registered as
-                double attributes in the functor class.  The function fnc
-                must be picklable and it must return a float.
-    replace  -- when set replace any PDFEnvelope type already registered
-                under the name.  Otherwise raise RuntimeError when the
-                name is taken.
-    dbattrs  -- optional float parameters of the wrapped function.
-                These will be registered as double attributes in the
-                functor class.  The wrapped function must be callable as
-                fnc(x, **dbattrs).  Make sure to pick attribute names that
-                do not conflict with other PDFCalculator attributes.
+    Attributes
+    ----------
+    name
+        unique string name for registering Python function in the
+        global registry of PDFEnvelope types.  This will be the
+        string identifier for the createByType factory.
+    fnc
+        Python function of a floating point argument and optional
+        float parameters.  The parameters need to be registered as
+        double attributes in the functor class.  The function fnc
+        must be picklable and it must return a float.
+    replace
+        when set replace any PDFEnvelope type already registered
+        under the name.  Otherwise raise RuntimeError when the
+        name is taken.
+    dbattrs
+        optional float parameters of the wrapped function.
+        These will be registered as double attributes in the
+        functor class.  The wrapped function must be callable as
+        fnc(x, **dbattrs).  Make sure to pick attribute names that
+        do not conflict with other PDFCalculator attributes.
 
     Return an instance of the new PDFEnvelope class.