Fix docstrings for API reference.

Author: Tieqiong

doc/source/conf.py

@@ -116,6 +116,11 @@
 # Display all warnings for missing links.
 nitpicky = True
 
+nitpick_ignore = [
+    ("py:class", "array_like"),
+    ("py:class", "Parser"),
+]
+
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -287,3 +292,7 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 # intersphinx_mapping = {'http://docs.python.org/': None}
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+}

src/diffpy/structure/__init__.py

@@ -13,15 +13,22 @@
 #
 ##############################################################################
 
-"""classes related to structure of materials
+"""
+Classes related to the structure of materials.
+
 Classes:
     Atom
+
     Lattice
+
     Structure
+
     PDFFitStructure
 Exceptions:
     StructureFormatError
+
     LatticeError
+
     SymmetryError
 """
 
@@ -51,13 +58,13 @@ def loadStructure(filename, fmt="auto", **kw):
 
     filename : str
         Path to the file to be loaded.
-    fmt : str, optional
-        Format of the structure file such as 'cif' or 'xyz'.  Must be
+    fmt : str, Optional
+        Format of the structure file such as 'cif' or 'xyz'. Must be
         one of the formats listed by the `parsers.inputFormats` function.
         When 'auto', all supported formats are tried in a sequence.
-    kw : misc, optional
+    kw : Optional
         Extra keyword arguments that are passed to `parsers.getParser`
-        function.  These configure the dedicated Parser object that
+        function. These configure the dedicated Parser object that
         is used to read content in filename.
 
     Returns

src/diffpy/structure/apps/anyeye.py

@@ -13,24 +13,37 @@
 #
 ##############################################################################
 
-"""anyeye    view structure file in atomeye
+"""
+anyeye view structure file in atomeye
+
 Usage: anyeye [options] strufile
 
-anyeye understands more structure formats than atomeye.  It converts strufile
-to a temporary XCFG file which is opened in atomeye.  Supported file formats:
+Anyeye understands more structure formats than atomeye. It converts strufile
+to a temporary XCFG file which is opened in atomeye. Supported file formats:
   inputFormats
 
 Options:
-  -f, --formula     override chemical formula in strufile, formula defines
-                    elements in the same order as in strufile, e.g, Na4Cl4
-  -w, --watch       watch input file for changes
-  --viewer=VIEWER   the structure viewer program, by default "atomeye".
-                    The program will be executed as "VIEWER structurefile"
-  --formats=FORMATS comma separated list of file formats that are understood
-                    by the VIEWER, by default "xcfg,pdb".  Files of other
-                    formats will be converted to the first listed format.
-  -h, --help        display this message and exit
-  -V, --version     show script version and exit
+  -f, --formula
+      Override chemical formula in strufile. The formula defines
+      elements in the same order as in strufile, e.g., Na4Cl4.
+
+  -w, --watch
+      Watch input file for changes.
+
+  --viewer=VIEWER
+      The structure viewer program, by default "atomeye".
+      The program will be executed as "VIEWER structurefile".
+
+  --formats=FORMATS
+      Comma-separated list of file formats that are understood
+      by the VIEWER, by default "xcfg,pdb". Files of other
+      formats will be converted to the first listed format.
+
+  -h, --help
+      Display this message and exit.
+
+  -V, --version
+      Show script version and exit.
 """
 
 from __future__ import print_function

src/diffpy/structure/atom.py

@@ -39,27 +39,27 @@ class Atom(object):
 
     Parameters
     ----------
-    atype : str or Atom, optional
+    atype : str or Atom, Optional
         The string atom type to be set as the `element` attribute.
         By default an empty string.  When of the *Atom* type, create
         a copy of *atype* and adjust it per other arguments.
-    xyz : ndarray, optional
+    xyz : numpy.ndarray, Optional
         Fractional coordinates within the associated `lattice`.
         By default ``[0, 0, 0]``.
-    label : str, optional
+    label : str, Optional
         A unique string `label` for referring to this Atom.
         By default an empty string.
-    occupancy : float, optional
+    occupancy : float, Optional
         The initial `occupancy` of this atom, by default ``1``.
-    anisotropy : bool, optional
+    anisotropy : bool, Optional
         The flag for anisotropic thermal displacements parameters.
         This overrides `anisotropy` implied by presence of the
         *U* or *Uisoequiv* arguments.  Defaults to ``False``
         when not set in any other way.
-    U : ndarray, optional
+    U : numpy.ndarray, Optional
         The 3x3 matrix of anisotropic thermal displacement parameters.
         When present `anisotropy` defaults to ``True``.
-    Uisoequiv: float, optional
+    Uisoequiv: float, Optional
         The isotropic atomic displacement parameter.  The `anisotropy`
         defaults to ``False`` when present.  Only one of the *U* and
         *Uisoequiv* arguments may be provided at the same time.  Assume
@@ -72,7 +72,7 @@ class Atom(object):
     ----------
     element : str
         The string type of the atom.  An element or ion symbol.
-    xyz : ndarray
+    xyz : numpy.ndarray
         The fractional coordinates in the associated `lattice`.
     label : str
         A unique string label referring to this atom, for example, "C_1".
@@ -211,7 +211,7 @@ def __copy__(self, target=None):
 
         Parameters
         ----------
-        target : Atom, optional
+        target : Atom, Optional
             An already existing Atom object to be updated to a duplicate
             of this Atom.  Create a new Atom object when not specified.
             This facilitates extension of the `__copy__` method
@@ -254,7 +254,7 @@ def __copy__(self, target=None):
     @property
     def xyz_cartn(self):
         """
-        ndarray: Atom position in absolute Cartesian coordinates.
+        numpy.ndarray: Atom position in absolute Cartesian coordinates.
 
         This is computed from fractional coordinates `xyz` and the
         current `lattice` setup.  Assignment to *xyz_cartn* or
@@ -305,7 +305,7 @@ def anisotropy(self, value):
     @property
     def U(self):
         """
-        ndarray : The 3x3 matrix of anisotropic atomic displacements.
+        numpy.ndarray : The 3x3 matrix of anisotropic atomic displacements.
 
         For isotropic displacements (when `anisotropy` is ``False``)
         assignment to *U* uses only the first ``Unew[0, 0]`` element

src/diffpy/structure/expansion/makeellipsoid.py

@@ -36,17 +36,26 @@ def makeSphere(S, radius):
 
 
 def makeEllipsoid(S, a, b=None, c=None):
-    """Cut a structure out of another one.
-
-    Arguments
-    S       --  A Structure instance
-    a       --  primary equatorial radius (along x-axis)
-    b       --  secondary equatorial radius (along y-axis). If b is None
-                (default) then it is set equal to a
-    c       --  polar radius (along z-axis). If c is None (default), then it is
-                set equal to a.
-
-    Returns a new structure instance
+    """
+    Cut a structure out of another one.
+
+    Parameters
+    ----------
+    S :
+        A Structure instance.
+    a :
+        Primary equatorial radius (along x-axis).
+    b :
+        Secondary equatorial radius (along y-axis). If b is None
+        (default), then it is set equal to a.
+    c :
+        Polar radius (along z-axis). If c is None (default), then it is
+        set equal to a.
+
+    Returns
+    -------
+    Structure :
+        A new structure instance.
     """
     if b is None:
         b = a

src/diffpy/structure/expansion/supercell_mod.py

@@ -22,19 +22,32 @@
 
 
 def supercell(S, mno):
-    """Perform supercell expansion for a structure.
+    """
+    Perform supercell expansion for a structure.
 
     New lattice parameters are multiplied and fractional coordinates
     divided by corresponding multiplier.  New atoms are grouped with
     their source in the original cell.
 
-    S   -- an instance of Structure from diffpy.structure.
-    mno -- sequence of 3 integers for cell multipliers along
-           the a, b and c axes.
+    Parameters
+    ----------
+    S :
+        An instance of Structure from diffpy.structure.
+    mno :
+        Sequence of 3 integers for cell multipliers along
+        the a, b and c axes.
+
+    Returns
+    -------
+    Structure
+        A new structure instance representing the expanded supercell.
 
-    Return a new expanded structure instance.
-    Raise TypeError when S is not Structure instance.
-    Raise ValueError for invalid mno argument.
+    Raises
+    ------
+    TypeError
+        S is not a Structure instance.
+    ValueError
+        Invalid mno argument.
     """
     # check arguments
     if len(mno) != 3: