docs: update docstrings (#419)

Update docstrings for sphinx.

README.md

@@ -1,7 +1,7 @@
 
 <img src="https://raw.githubusercontent.com/modflowpy/flopy/master/examples/images/flopy3.png" alt="flopy3" style="width:50;height:20">
 
-### Version 3.2.9 develop &mdash; build 216
+### Version 3.2.9 develop &mdash; build 218
 [![Build Status](https://travis-ci.org/modflowpy/flopy.svg?branch=develop)](https://travis-ci.org/modflowpy/flopy)
 [![PyPI Version](https://img.shields.io/pypi/v/flopy.png)](https://pypi.python.org/pypi/flopy)
 [![Coverage Status](https://coveralls.io/repos/github/modflowpy/flopy/badge.svg?branch=develop)](https://coveralls.io/github/modflowpy/flopy?branch=develop)

autotest/t042_test.py

@@ -6,7 +6,8 @@
 sys.path.append('/Users/aleaf/Documents/GitHub/flopy3')
 import numpy as np
 import flopy
-from flopy.utils.postprocessing import get_transmissivities, get_water_table, get_gradients, get_saturated_thickness
+from flopy.utils.postprocessing import get_transmissivities, get_water_table, \
+    get_gradients, get_saturated_thickness
 
 mf = flopy.modflow
 

code.json

@@ -29,7 +29,7 @@
         "downloadURL": "https://code.usgs.gov/usgs/modflow/flopy/archive/master.zip", 
         "vcs": "git", 
         "laborHours": -1, 
-        "version": "3.2.9.216", 
+        "version": "3.2.9.218", 
         "date": {
             "metadataLastUpdated": "2018-10-17"
         }, 

flopy/export/metadata.py

@@ -8,23 +8,31 @@
 
 
 class acdd:
-    """Translate ScienceBase global metadata attributes to CF and ACDD
+    """
+    Translate ScienceBase global metadata attributes to CF and ACDD
     global attributes.
-    
-    see:
-    https://www.sciencebase.gov/catalog/
-    http://cfconventions.org/cf-conventions/v1.6.0/cf-conventions.html#description-of-file-contents
-    http://wiki.esipfed.org/index.php/Attribute_Convention_for_Data_Discovery
-    
+
     Parameters
     ----------
+
     sciencebase_id : str
         Unique identifier for ScienceBase record (e.g. 582da7efe4b04d580bd37be8)
     model : flopy model object
-    
+        Model object
+
+    References
+    ----------
+
+    https://www.sciencebase.gov/catalog/
+    http://cfconventions.org/cf-conventions/v1.6.0/cf-conventions.html#description-of-file-contents
+    http://wiki.esipfed.org/index.php/Attribute_Convention_for_Data_Discovery
+
     """
 
     def __init__(self, sciencebase_id, model):
+        """
+        Class constructor
+        """
 
         self.id = sciencebase_id
         self.model = model
@@ -120,30 +128,47 @@ def creator_url(self):
 
     @property
     def geospatial_bounds(self):
-        """Describes the data's 2D or 3D geospatial extent in OGC's Well-Known Text (WKT) Geometry format"""
-        return 'POLYGON (({0} {2}, {0} {3}, {1} {3}, {1} {2}, {0} {2}))'.format(
-            self.geospatial_lon_min,
-            self.geospatial_lon_max,
-            self.geospatial_lat_min,
-            self.geospatial_lat_max
-        )
+        """
+        Describes the data's 2D or 3D geospatial extent in OGC's Well-Known
+        Text (WKT) Geometry format
+        """
+        fmt = '(({0} {2}, {0} {3}, {1} {3}, {1} {2}, {0} {2}))'
+        bounds = 'POLYGON ' + fmt.format(self.geospatial_lon_min,
+                                         self.geospatial_lon_max,
+                                         self.geospatial_lat_min,
+                                         self.geospatial_lat_max)
+        return bounds
 
     @property
     def geospatial_bounds_vertical_crs(self):
-        """The vertical coordinate reference system (CRS) 
-        for the Z axis of the point coordinates in the geospatial_bounds attribute. """
+        """
+        The vertical coordinate reference system (CRS) for the Z axis of
+        the point coordinates in the geospatial_bounds attribute.
+        """
         epsg = {'NGVD29': 'EPSG:5702', 'NAVD88': 'EPSG:5703'}
         return epsg.get(self.vertical_datum)
 
     @property
     def references(self):
+        """
+
+        Returns
+        -------
+
+        """
         r = [self.citation]
         links = [d.get('uri') for d in self.sb['webLinks']
                  if 'link' in d.get('type').lower()]
         return r + links
 
     @property
     def time_coverage(self):
+        """
+
+        Returns
+        -------
+
+        """
         l = self.sb['dates']
         tc = {}
         for t in ['start', 'end']:
@@ -162,7 +187,9 @@ def time_coverage(self):
 
     @property
     def vertical_datum(self):
-        """try to parse the vertical datum from the xml info"""
+        """
+        Try to parse the vertical datum from the xml info
+        """
         altdatum = self._get_xml_attribute('altdatum')
         if altdatum is not None:
             if '88' in altdatum:
@@ -174,7 +201,9 @@ def vertical_datum(self):
 
     @property
     def xmlroot(self):
-        """ElementTree root element object for xml metadata"""
+        """
+        ElementTree root element object for xml metadata
+        """
         try:
             return self.get_sciencebase_xml_metadata()
         except:
@@ -185,9 +214,10 @@ def xmlfile(self):
         return self.sb['identifiers'][0].get('key')
 
     def get_sciencebase_metadata(self, id):
-        """Gets metadata json text for given ID from sciencebase.gov; loads
+        """
+        Gets metadata json text for given ID from sciencebase.gov; loads
         into python dictionary. Fetches the reference text using the url:
-            https://www.sciencebase.gov/catalog/item/<ID>?format=json
+        https://www.sciencebase.gov/catalog/item/<ID>?format=json
 
         Parameters
         ----------
@@ -205,13 +235,14 @@ def get_sciencebase_metadata(self, id):
 
         import json
         from flopy.utils.flopy_io import get_url_text
-        text = get_url_text(url,
-                            error_msg='Need an internet connection to get metadata from ScienceBase.')
+        msg = 'Need an internet connection to get metadata from ScienceBase.'
+        text = get_url_text(url, error_msg=msg)
         if text is not None:
             return json.loads(text)
 
     def get_sciencebase_xml_metadata(self):
-        """Gets xml from sciencebase.gov, using XML url obtained
+        """
+        Gets xml from sciencebase.gov, using XML url obtained
         from json using get_sciencebase_metadata().
 
         Parameters
@@ -229,6 +260,6 @@ def get_sciencebase_xml_metadata(self):
         from flopy.utils.flopy_io import get_url_text
 
         url = self.xmlfile
-        text = get_url_text(url,
-                            error_msg='Need an internet connection to get metadata from ScienceBase.')
+        msg = 'Need an internet connection to get metadata from ScienceBase.'
+        text = get_url_text(url, error_msg=msg)
         return ET.fromstring(text)

flopy/mbase.py

@@ -649,16 +649,24 @@ def remove_external(self, fname=None, unit=None):
 
     def add_existing_package(self, filename, ptype=None,
                              copy_to_model_ws=True):
-        """ add an existing package to a model instance.
+        """
+        Add an existing package to a model instance.
+
         Parameters
         ----------
+
         filename : str
             the name of the file to add as a package
         ptype : optional
             the model package type (e.g. "lpf", "wel", etc).  If None,
             then the file extension of the filename arg is used
         copy_to_model_ws : bool
             flag to copy the package file into the model_ws directory.
+
+        Returns
+        -------
+        None
+
         """
         if ptype is None:
             ptype = filename.split('.')[-1]

flopy/mf6/mfbase.py

@@ -182,22 +182,26 @@ class MFFileMgmt(object):
 
     Parameters
     ----------
+
     path : string
         path on disk to the simulation
 
     Attributes
     ----------
+
     sim_path : string
         path to the simulation
     model_relative_path : OrderedDict
         dictionary of relative paths to each model folder
 
     Methods
     -------
+
     get_model_path : (key : string) : string
         returns the model working path for the model key
-    set_sim_path
+    set_sim_path : string
         sets the simulation working path
+
     """
     def __init__(self, path):
         self._sim_path = ''

flopy/mf6/utils/binaryfile_utils.py

@@ -217,8 +217,8 @@ def _get_vertices(mfdict, key):
         try:
             import pandas as pd
         except Exception as e:
-            print("this feature requires pandas")
-            return None
+            msg = 'MFOutputRequester._get_vertices(): requires pandas'
+            raise ImportError(msg)
 
         mname = key[0]
         cellid = mfdict[(mname, 'DISV8', 'CELL2D', 'cell2d_num')]

flopy/modflow/mffhb.py

@@ -78,6 +78,7 @@ class ModflowFhb(Package):
                 [lay, row, col, iaux, flwrat1, flwra2, ..., flwrat(nbdtime)],
                 [lay, row, col, iaux, flwrat1, flwra2, ..., flwrat(nbdtime)]
             ]
+
         Note there should be nflw rows in ds7.
 
     cnstm7 : float
@@ -96,6 +97,7 @@ class ModflowFhb(Package):
                 [lay, row, col, iaux, sbhed1, sbhed2, ..., sbhed(nbdtime)],
                 [lay, row, col, iaux, sbhed1, sbhed2, ..., sbhed(nbdtime)]
             ]
+
         Note there should be nhed rows in ds7.
 
     extension : string

flopy/modflow/mfhob.py

@@ -446,7 +446,7 @@ class HeadObservation(object):
         is the zero-based layer index of the cell in which the head observation
         is located. If layer is less than zero, hydraulic heads from multiple
         layers are combined to calculate a simulated value. The number of
-        layers equals the absolute value of layer, or |layer|. Default is 0.
+        layers equals the absolute value of layer, or abs(layer). Default is 0.
     row : int
         zero-based row index for the observation. Default is 0.
     column : int
@@ -464,7 +464,7 @@ class HeadObservation(object):
         observations. itt = 1 specified for heads and itt = 2 specified
         if initial value is head and subsequent changes in head. Only
         specified if irefsp is < 0. Default is 1.
-    mlay : dictionary of length (|irefsp|)
+    mlay : dictionary of length (abs(irefsp))
         key represents zero-based layer numbers for multilayer observations an
         value represents the fractional value for each layer of multilayer
         observations. If mlay is None, a default mlay of {0: 1.} will be