Merge pull request #91 from Sparks29032/docs_build

Docstring Reformatting

Author: sbillinge

.travis.yml

@@ -13,27 +13,44 @@
 import sys
 import os
 sys.path.insert(0, os.path.abspath('../..'))
+sys.path.insert(0, os.path.abspath('../../src'))
 
 
 # -- Project information -----------------------------------------------------
 
 project = 'PDFmorph'
+project_full = 'diffpy.pdfmorph'
 copyright = '2009-2019, Trustees of Columbia University in the City of New York, all rights reserved.'
 author = 'Chris Farrow, Christopher J. Wright, Pavol Juhás, Chia-Hao (Timothy) Liu, S. Matthew Román, Simon J.L. Billinge'
 
 # The full version, including alpha/beta/rc tags
-release = '0.1.0'
+from importlib.metadata import version
+fullversion = version(project_full)
+# The short X.Y version.
+version = ''.join(fullversion.split('.post')[:1])
+# The full version, including alpha/beta/rc tags.
+release = fullversion
+
+# Get current date for copyright
+import time
+today = time.strftime('%B %d, %Y', time.localtime())
+year = today.split()[-1]
+copyright = copyright.replace('%Y', year)
 
 
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-import sphinx_rtd_theme
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 
-	'sphinx.ext.todo', 'sphinx.ext.viewcode', 
-	'sphinx.ext.intersphinx', 'm2r']
+extensions = ['sphinx.ext.autodoc',
+    'sphinx.ext.napoleon', 
+	'sphinx.ext.todo',
+    'sphinx.ext.viewcode', 
+	'sphinx.ext.intersphinx',
+    'sphinx_rtd_theme',
+    'm2r',
+]
 napoleon_google_docstring = False
 napoleon_use_param = False
 napoleon_use_ivar = False
@@ -61,6 +78,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
+import sphinx_rtd_theme
 html_theme = 'sphinx_rtd_theme'
 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 

doc/source/conf.py

@@ -1,16 +1,16 @@
 PDFmorph.morph_helpers Package
-#######################
+##############################
 
 diffpy.pdfmorph.morph_helpers.transformpdftordf module
-===========================================
+======================================================
 
 .. automodule:: diffpy.pdfmorph.morph_helpers.transformpdftordf
     :members:
     :undoc-members:
     :show-inheritance:
 
 diffpy.pdfmorph.morph_helpers.transformrdftopdf module
-===========================================
+======================================================
 
 .. automodule:: diffpy.pdfmorph.morph_helpers.transformrdftopdf
     :members:

doc/source/morph_helpers.rst

@@ -34,10 +34,10 @@ Basic PDFmorph Workflow
           explore in this tutorial.
 
 	3. Using the ``mkdir`` command, create a directory where you'll
-       store the tutorial PDF files and use the ``cd`` command to change
-       into that directory. You can download the tutorial files
-       :download:`here <../../tests/testdata/tutorialData.zip>`.
-       Then, ``cd`` into the ``tutorialData`` directory.
+           store the tutorial PDF files and use the ``cd`` command to change
+           into that directory. You can download the tutorial files
+           :download:`here <../../tutorial/tutorialData.zip>`.
+           Then, ``cd`` into the ``tutorialData`` directory.
 
         * The files in this dataset were collected by Soham Banerjee
           at Brookhaven National Laboratory in Upton, New York.

doc/source/quickstart.rst

@@ -29,8 +29,13 @@
 def set_verbosity(vb):
     '''Set verbosity of the pdfmorph logger.
 
-    vb   -- integer or one of ('debug', 'info', 'warning', 'error') strings
+    Parameters
+    ----------
+    vb
+        Integer or one of ('debug', 'info', 'warning', 'error') strings.
 
+    Returns
+    -------
     No return value.
     '''
     try:

src/diffpy/pdfmorph/log.py

@@ -26,41 +26,59 @@
 class Morph(object):
     '''Base class for implementing a morph given a target.
 
-    Adapted from diffpy.pdfgetx to include two sets of arrays that get passed
-    through.
-
-    Note that attributes are taken from config when not found locally. The
-    morph may modify the config dictionary. This is the means by which to
-    communicate automatically modified attributes.
-
-    Class attributes:
-
-    summary      -- short description of a morph
-    xinlabel     -- descriptive label for the x input array
-    yinlabel     -- descriptive label for the y input array
-    xoutlabel    -- descriptive label for the x output array
-    youtlabel    -- descriptive label for the y output array
-    parnames     -- list of names of configuration variables
-
-    Instance attributes:
-
-    config      -- dictionary that contains all configuration variables
-    x_morph_in      -- last morph input x data
-    y_morph_in      -- last morph input y data
-    x_morph_out     -- last morph result x data
-    y_morph_out     -- last morph result y data
-    x_target_in      -- last target input x data
-    y_target_in      -- last target input y data
-    x_target_out     -- last target result x data
-    y_target_out     -- last target result y data
-
-    Properties:
-
-    xy_morph_in     -- tuple of (x_morph_in, y_morph_in)
-    xy_morph_out    -- tuple of (x_morph_out, y_morph_out)
-    xy_target_in     -- tuple of (x_target_in, y_target_in)
-    xy_target_out    -- tuple of (x_target_out, y_target_out)
-    xyallout    -- tuple of (x_morph_out, y_morph_out, x_target_out, y_target_out)
+    Adapted from diffpy.pdfgetx to include two sets of arrays that get passed through.
+
+    Attributes are taken from config when not found locally. The morph may modify the config dictionary.
+    This is the means by which to communicate automatically modified attributes.
+
+    Class Attributes
+    ----------------
+    summary
+        Short description of a morph.
+    xinlabel
+        Descriptive label for the x input array.
+    yinlabel
+        Descriptive label for the y input array.
+    xoutlabel
+        Descriptive label for the x output array.
+    youtlabel
+        Descriptive label for the y output array.
+    parnames: list
+        Names of configuration variables.
+
+    Instance Attributes
+    -------------------
+    config: dict
+        All configuration variables.
+    x_morph_in
+        Last morph input x data.
+    y_morph_in
+        Last morph input y data.
+    x_morph_out
+        Last morph result x data.
+    y_morph_out
+        Last morph result y data.
+    x_target_in
+        Last target input x data.
+    y_target_in
+        Last target input y data.
+    x_target_out
+        Last target result x data.
+    y_target_out
+        Last target result y data.
+
+    Properties
+    ----------
+    xy_morph_in
+        Tuple of (x_morph_in, y_morph_in).
+    xy_morph_out
+        Tuple of (x_morph_out, y_morph_out).
+    xy_target_in
+        Tuple of (x_target_in, y_target_in).
+    xy_target_out
+        Tuple of (x_target_out, y_target_out).
+    xyallout
+        Tuple of (x_morph_out, y_morph_out, x_target_out, y_target_out).
     '''
 
     # Class variables
@@ -98,7 +116,8 @@ class Morph(object):
     def __init__(self, config=None):
         '''Create a default Morph instance.
 
-        config  -- dictionary that contains all configuration variables
+        config: dict
+            All configuration variables.
         '''
         # declare empty attributes
         if config is None:
@@ -118,13 +137,19 @@ def __init__(self, config=None):
     def morph(self, x_morph, y_morph, x_target, y_target):
         '''Morph arrays morphed or target.
 
-        x_morph, y_morph  --  Morphed arrays.
-        x_target, y_target  --  Target arrays.
+        Identity operation. This method should be overloaded in a derived class.
 
-        Identity operation.  This method should be overloaded in a derived
-        class.
+        Parameters
+        ----------
+        x_morph, y_morph
+            Morphed arrays.
+        x_target, y_target
+            Target arrays.
 
-        Return a tuple of numpy arrays (x_morph_out, y_morph_out, x_target_out, y_target_out)
+        Returns
+        -------
+        tuple
+            A tuple of numpy arrays (x_morph_out, y_morph_out, x_target_out, y_target_out)
         '''
         self.x_morph_in = x_morph
         self.y_morph_in = y_morph
@@ -144,15 +169,20 @@ def __call__(self, x_morph, y_morph, x_target, y_target):
     def applyConfig(self, config):
         '''Process any configuration data from a dictionary.
 
-        config   -- Configuration dictionary.
+        Parameters
+        ----------
+        config: dict
+            Configuration dictionary.
 
+        Returns
+        -------
         No return value.
         '''
         self.config = config
         return
 
     def checkConfig(self):
-        '''Verify data in self.config.  No action by default.
+        '''Verify data in self.config. No action by default.
 
         To be overridden in a derived class.
         '''
@@ -161,9 +191,15 @@ def checkConfig(self):
     def plotInputs(self, xylabels=True):
         '''Plot input arrays using matplotlib.pyplot
 
-        xylabels -- flag for updating x and y axes labels
+        Parameters
+        ----------
+        xylabels
+            Flag for updating x and y axes labels.
 
-        Return a list of matplotlib line objects.
+        Returns
+        -------
+        list:
+            A list of matplotlib line objects.
         '''
         from matplotlib.pyplot import plot, xlabel, ylabel
 
@@ -177,11 +213,17 @@ def plotInputs(self, xylabels=True):
     def plotOutputs(self, xylabels=True, **plotargs):
         '''Plot output arrays using matplotlib.pyplot
 
-        xylabels -- flag for updating x and y axes labels
-        plotargs -- arguments passed to the pylab plot function. Note that
-                    "label" will be ignored.
-
-        Return a list of matplotlib line objects.
+        Parameters
+        ----------
+        xylabels: bool
+            Flag for updating x and y axes labels.
+        plotargs
+            Arguments passed to the pylab plot function. Note that "label" will be ignored.
+
+        Returns
+        -------
+        list
+            A list of matplotlib line objects.
         '''
         from matplotlib.pyplot import plot, xlabel, ylabel
 
@@ -197,10 +239,19 @@ def plotOutputs(self, xylabels=True, **plotargs):
     def __getattr__(self, name):
         '''Obtain the value from self.config, when normal lookup fails.
 
-        name -- name of the attribute to be recovered
+        Parameters
+        ----------
+        name
+            Name of the attribute to be recovered.
+
+        Returns
+        -------
+        self.config.get(name)
 
-        Return self.config.get(name).
-        Raise AttributeError, when name is not available from self.config.
+        Raises
+        ------
+        AttributeError
+            Name is not available from self.config.
         '''
         if name in self.config:
             return self.config[name]
@@ -211,9 +262,12 @@ def __getattr__(self, name):
     def __setattr__(self, name, val):
         '''Set configuration variables to config.
 
-        name -- name of the attribute
-        val  -- value of the attribute
-
+        Parameters
+        ----------
+        name
+            Name of the attribute.
+        val
+            Value of the attribute.
         '''
         if name in self.parnames:
             self.config[name] = val