update docs, closes pvlib#592

Author: mikofski

docs/sphinx/source/api.rst

@@ -340,6 +340,7 @@ relevant to solar energy modeling.
    iotools.get_ecmwf_macc
    iotools.read_crn
    iotools.read_solrad
+   iotools.get_psm3
 
 A :py:class:`~pvlib.location.Location` object may be created from metadata
 in some files.

docs/sphinx/source/whatsnew/v0.6.2.rst

@@ -29,6 +29,7 @@ Enhancements
 * Add US CRN data reader to :ref:`iotools`.
 * Add SOLRAD data reader to :ref:`iotools`.
 * Add EPW data reader to :ref:`iotools`. (:issue:`591`)
+* Add PSM3 reader to :ref:`iotools`. (:issue:`592`)
 
 Bug fixes
 ~~~~~~~~~

pvlib/iotools/psm3.py

@@ -19,7 +19,76 @@
 
 
 def get_psm3(latitude, longitude, tmy='tmy', interval=60):
-    """get psm3"""
+    """
+    Get PSM3 data
+
+    Parameters
+    ----------
+    latitude : float or int
+        in decimal degrees, between -90 and 90, north is positive
+    longitude : float or int
+        in decimal degrees, between -180 and 180, east is positive
+    tmy : str
+        PSM3 parameter "name", see notes below for options, default is ``'tmy'``
+    interval : integer
+        interval size in minutes, can be only either 30 or 60 minutes
+
+    Returns
+    -------
+    headers : dict
+        meta data from NREL PSM-3 about the record, see notes for fields
+    data : pandas.DataFrame
+        timeseries data from NREL PSM3
+
+    Raises
+    ------
+    requests.HTTPError
+
+    Notes
+    -----
+    The ``tmy`` parameter 'names' must be a single value from the following
+    list:
+
+        ['1998', '1999', '2000', '2001', '2002', '2003', '2004', '2005',
+         '2006', '2007', '2008', '2009', '2010', '2011', '2012', '2013',
+         '2014', '2015', '2016', '2017', 'tmy', 'tmy-2016', 'tmy-2017',
+         'tdy-2017', 'tgy-2017']
+
+    The return is a tuple with two items. The first item is a header with meta
+    data from NREL PSM3 about the record containing the following fields:
+
+    * Source
+    * Location ID
+    * City
+    * State
+    * Country
+    * Latitude
+    * Longitude
+    * Time Zone
+    * Elevation
+    * Local Time Zone
+    * Dew Point Units
+    * DHI Units
+    * DNI Units
+    * GHI Units
+    * Temperature Units
+    * Pressure Units
+    * Wind Direction Units
+    * Wind Speed
+    * Surface Albedo Units
+    * Version
+
+    See Also
+    --------
+    pvlib.iotools.read_tmy2, pvlib.iotools.read_tmy3
+
+    References
+    ----------
+    [1] `NREL Developer Network - Physical Solar Model (PSM) v3
+        <https://developer.nrel.gov/docs/solar/nsrdb/psm3_data_download/>`_
+    [2] `NREL National Solar Radiation Database (NSRDB)
+        <https://nsrdb.nrel.gov/>`_
+    """
     longitude = ('%9.4f' % longitude).strip()
     latitude = ('%8.4f' % latitude).strip()
     params = {