Merge pull request #80 from Tieqiong/docstrings

Update docstrings and format api

Author: sbillinge

doc/source/conf.py

@@ -48,6 +48,8 @@
     "m2r",
 ]
 
+autodoc_member_order = "groupwise"
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -121,6 +123,7 @@
 nitpick_ignore = [
     ("py:class", "array_like"),
     ("py:class", "Parser"),
+    ("py:class", "CifFile"),
 ]
 
 # -- Options for HTML output ----------------------------------------------

src/diffpy/Structure.py

@@ -13,12 +13,13 @@
 #
 ##############################################################################
 
-"""
-Support import of old camel-case module names with DeprecationWarning.
+"""Support import of old camel-case module names with `DeprecationWarning`.
 
 The imported camel-case modules are aliases for the current module
-instances.  Their `__name__` attributes are thus all in lower-case.
+instances. Their `__name__` attributes are thus all in lower-case.
 
+Warning
+-------
 This module is deprecated and will be removed in the future.
 """
 

src/diffpy/structure/__init__.py

@@ -14,22 +14,25 @@
 ##############################################################################
 
 """
-Classes related to the structure of materials.
+Crystal structure container and parsers for structure formats.
 
-Classes:
-    Atom
+Classes related to the structure of materials:
+    * Atom
+    * Lattice
+    * Structure
+    * PDFFitStructure
 
-    Lattice
+Other classes:
+    * SpaceGroup
+    * SymOp
+    * ExpandAsymmetricUnit
+    * GeneratorSite
+    * SymmetryConstraints
 
-    Structure
-
-    PDFFitStructure
 Exceptions:
-    StructureFormatError
-
-    LatticeError
-
-    SymmetryError
+    * StructureFormatError
+    * LatticeError
+    * SymmetryError
 """
 
 # Interface definitions ------------------------------------------------------
@@ -44,14 +47,11 @@
 # package version
 from diffpy.structure.version import __version__
 
-"""Crystal structure container and parsers for structure formats."""
-
 # top level routines
 
 
 def loadStructure(filename, fmt="auto", **kw):
-    """
-    Load new structure object from the specified file.
+    """Load new structure object from the specified file.
 
     Parameters
     ----------

src/diffpy/structure/_legacy_importer.py

@@ -17,19 +17,23 @@
 Support import of old camel-case module names with DeprecationWarning.
 
 The imported camel-case modules are aliases for the current module
-instances.  Their `__name__` attributes are thus all in lower-case.
+instances. Their `__name__` attributes are thus all in lower-case.
 
-This module is deprecated and will be removed in the future.
+Note
+----
+this module must be only imported from `diffpy.Structure`.
 
-NOTE: this module must be only imported from `diffpy.Structure`.
+Warning
+-------
+This module is deprecated and will be removed in the future.
 """
 
 
 import importlib.abc
 import sys
 from warnings import warn
 
-WMSG = "Module {!r} is deprecated.  Use {!r} instead."
+WMSG = "Module {!r} is deprecated. Use {!r} instead."
 
 # ----------------------------------------------------------------------------
 
@@ -56,9 +60,7 @@ def find_spec(self, fullname, path=None, target=None):
 
 
 class MapRenamedStructureModule(importlib.abc.Loader):
-    """
-    Loader for old camel-case module names.
-
+    """Loader for old camel-case module names.
     Import the current module and alias it under the old name.
     """
 

src/diffpy/structure/apps/__init__.py

@@ -13,5 +13,5 @@
 #
 ##############################################################################
 
-"""Script applications that use the diffpy.structure package.
+"""Script applications that use the `diffpy.structure` package.
 """

src/diffpy/structure/apps/anyeye.py

@@ -14,18 +14,18 @@
 ##############################################################################
 
 """
-anyeye view structure file in atomeye
+Anyeye view structure file in atomeye.
 
-Usage: anyeye [options] strufile
+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:
-  inputFormats
+Anyeye understands more `Structure` formats than atomeye. It converts `strufile`
+to a temporary XCFG file which is opened in atomeye. See supported file formats:
+``inputFormats``
 
 Options:
   -f, --formula
-      Override chemical formula in strufile. The formula defines
-      elements in the same order as in strufile, e.g., Na4Cl4.
+      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.
@@ -36,7 +36,7 @@
 
   --formats=FORMATS
       Comma-separated list of file formats that are understood
-      by the VIEWER, by default "xcfg,pdb". Files of other
+      by the VIEWER, by default ``"xcfg,pdb"``. Files of other
       formats will be converted to the first listed format.
 
   -h, --help
@@ -65,7 +65,7 @@
 
 
 def usage(style=None):
-    """show usage info, for style=="brief" show only first 2 lines"""
+    """Show usage info, for ``style=="brief"`` show only first 2 lines."""
     import os.path
 
     myname = os.path.basename(sys.argv[0])
@@ -91,7 +91,17 @@ def version():
 def loadStructureFile(filename, format="auto"):
     """Load structure from specified file.
 
-    Return a tuple of (Structure, fileformat).
+    Parameters
+    ----------
+    filename : str
+        Path to the structure file.
+    format : str, Optional
+        File format, by default "auto".
+
+    Returns
+    -------
+    tuple
+        A tuple of (Structure, fileformat).
     """
     from diffpy.structure import Structure
 
@@ -165,7 +175,7 @@ def cleanUp(pd):
 
 
 def parseFormula(formula):
-    """parse chemical formula and return a list of elements"""
+    """Parse chemical formula and return a list of elements"""
     # remove all blanks
     formula = re.sub(r"\s", "", formula)
     if not re.match("^[A-Z]", formula):

src/diffpy/structure/apps/transtru.py

@@ -13,22 +13,26 @@
 #
 ##############################################################################
 
-"""transtru   translate structure file to different format
-Usage: transtru INFMT..OUTFMT strufile
+"""Translate structure file to different format.
 
-translates structure file strufile from INFMT to OUTFMT format and prints it
-to the screen.  Use "-" as strufile to read from standard input.  To save the
+Usage: ``transtru INFMT..OUTFMT strufile``
+
+Translates structure file strufile from `INFMT` to `OUTFMT` format and prints it
+to the screen. Use "-" as `strufile` to read from standard input. To save the
 translated file, use
 
-    transtru INFMT..OUTFMT strufile > strufile.out
+    ``transtru INFMT..OUTFMT strufile > strufile.out``
 
 Supported input and output structure formats are
-  INFMT:   inputFormats
-  OUTFMT:  outputFormats
+    * `INFMT`: ``inputFormats``
+    * `OUTFMT`: ``outputFormats``
 
 Options:
-  -h, --help      display this message
-  -V, --version   show script version
+  -h, --help
+    Display this message.
+
+  -V, --version
+    Show script version.
 """
 
 from __future__ import print_function
@@ -40,7 +44,7 @@
 
 
 def usage(style=None):
-    """show usage info, for style=="brief" show only first 2 lines"""
+    """Show usage info, for ``style=="brief"`` show only first 2 lines."""
     import os.path
 
     myname = os.path.basename(sys.argv[0])