Fixed many docstrings

Went over sphinx warnings to fix many docstring formatting issues. Fixed a few minor comment issues (mainly adding a space after # comment symbol). Fixed intersphinx_mapping error in conf.py

docs/api.rst

@@ -1,5 +1,4 @@
-.. _api:
-
+.. title:: ulmo readers (API)
 
 ulmo Readers
 ============
@@ -19,6 +18,8 @@ strings, the ISO 8061 format ('YYYY-mm-dd HH:MM:SS' or some abbreviated version)
 is accepted, as well dates in 'mm/dd/YYYY' format.
 
 
+.. _api:
+
 California Department of Water Resources Historical Data
 ========================================================
 .. automodule:: ulmo.cdec.historical

docs/conf.py

@@ -222,4 +222,7 @@
 #latex_domain_indices = True
 
 # 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://docs.scipy.org/doc/numpy', None),
+}

ulmo/cuahsi/his_central/__init__.py

@@ -1,8 +1,7 @@
 """
-    ulmo.cuahsi.his_central
-    ~~~~~~~~~~~~~~~~~~~~~~~
-
-    `CUAHSI HIS Central`_ web services
+    CUAHSI HIS Central
+    ~~~~~~~~~~~~~~~~~~
+    `CUAHSI HIS Central`_ catalog web services
 
     .. _CUAHSI HIS Central: http://his.cuahsi.org/hiscentral.html
 """

ulmo/cuahsi/wof/__init__.py

@@ -1,8 +1,7 @@
 """
-    ulmo.cuahsi.wof
-    ~~~~~~~~~~~~~~~
-
-    `CUAHSI WaterOneFlow`_ web services
+    CUAHSI WaterOneFlow
+    ~~~~~~~~~~~~~~~~~~~
+    `CUAHSI WaterOneFlow`_ web data access services
 
     .. _CUAHSI WaterOneFlow: http://his.cuahsi.org/wofws.html
 """

ulmo/cuahsi/wof/core.py

@@ -35,7 +35,7 @@ def get_sites(wsdl_url, suds_cache=("default",), timeout=None):
         URL of a service's web service definition language (WSDL) description.
         All WaterOneFlow services publish a WSDL description and this url is the
         entry point to the service.
-    suds_cache : ``None`` or tuple
+    suds_cache : `None` or tuple
         SOAP local cache duration for WSDL description and client object.
         Pass a cache duration tuple like ('days', 3) to set a custom duration.
         Duration may be in months, weeks, days, hours, or seconds.

ulmo/lcra/hydromet/__init__.py

@@ -1 +1,11 @@
+"""
+    LCRA Hydromet Data
+    ~~~~~~~~~~~~~~~~~~
+    Access to hydrologic and climate data in the Colorado River Basin (Texas)
+    provided by the `Hydromet`_ web site and web service from
+    the `Lower Colorado River Authority`_.
+
+    .. _Lower Colorado River Authority: http://www.lcra.org
+    .. _Hydromet: http://hydromet.lcra.org
+"""
 from .core import get_sites_by_type, get_site_data, get_all_sites, get_current_data

ulmo/lcra/hydromet/core.py

@@ -4,6 +4,7 @@
     This module provides access to hydrologic and climate data in the Colorado
     River Basin (Texas) provided by the `Lower Colorado River Authority`_
     `Hydromet`_ web site and web service.
+
     .. _Lower Colorado River Authority: http://www.lcra.org
     .. _Hydromet: http://hydromet.lcra.org
 """
@@ -51,11 +52,13 @@
 
 def get_sites_by_type(site_type):
     """Gets list of the hydromet site codes and description for site.
-    Parameters:
-    -----------
+
+    Parameters
+    ----------
     site_type : str
         In all but lake sites, this is the parameter code collected at the site.
         For lake sites, it is 'lake'. See ``site_types`` and ``PARAMETERS``
+
     Returns
     -------
     sites_dict: dict
@@ -64,7 +67,7 @@ def get_sites_by_type(site_type):
     sites_base_url = 'http://hydromet.lcra.org/navgagelist.asp?Stype=%s'
     # the url doesn't provide list of sites for the following parameters but
     # they are available with the paired parameter. e.g., flow is available
-    #at stage sites.
+    # at stage sites.
     if site_type == 'winddir':
         site_type = 'windsp'
     if site_type == 'flow':
@@ -100,6 +103,7 @@ def get_all_sites():
 def get_current_data(service, as_geojson=False):
     """fetches the current (near real-time) river stage and flow values from
     LCRA web service.
+
     Parameters
     ----------
     service : str
@@ -108,10 +112,11 @@ def get_current_data(service, as_geojson=False):
     as_geojson : 'True' or 'False' (default)
         If True the data is returned as geojson featurecollection and if False
         data is returned as list of dicts.
+
     Returns
     -------
-    current_values_dicts : a list of dicts or
-    current_values_geojson : a geojson featurecollection.
+        current_values_dicts : a list of dicts or
+        current_values_geojson : a geojson featurecollection.
     """
     request_body_template = (
         '<?xml version="1.0" encoding="utf-8"?>\n'
@@ -160,6 +165,7 @@ def get_current_data(service, as_geojson=False):
 def get_site_data(site_code, parameter_code, as_dataframe=True,
                   start_date=None, end_date=None, dam_site_location='head'):
     """Fetches site's parameter data
+
     Parameters
     ----------
     site_code : str
@@ -206,7 +212,7 @@ def get_site_data(site_code, parameter_code, as_dataframe=True,
             parameter_code = 'STAGE'
     elif parameter_code == 'RHUMID':
         parameter_code = 'Rhumid'
-    #the parameter selection dropdown doesn't have flow. the data comes with stage.
+    # the parameter selection dropdown doesn't have flow. the data comes with stage.
     elif parameter_code == 'FLOW':
         parameter_code = 'STAGE'
     else:
@@ -327,7 +333,7 @@ def _extract_headers_for_next_request(request):
         if tag_dict.get('value', None) == 'tabular':
             #
             continue
-        #some tags don't have a value and are used w/ JS to toggle a set of checkboxes
+        # some tags don't have a value and are used w/ JS to toggle a set of checkboxes
         payload[tag_dict['name']] = tag_dict.get('value')
     return payload
 
@@ -339,7 +345,7 @@ def _make_next_request(url, previous_request, data):
 
 
 def _parse_val(val):
-    #the &nsbp translates to the following unicode
+    # the &nsbp translates to the following unicode
     if val == u'\xa0':
         return None
     else:

ulmo/lcra/waterquality/__init__.py

@@ -1 +1,11 @@
+"""
+    LCRA Water Quality Data
+    ~~~~~~~~~~~~~~~~~~~~~~~
+    Access to water quality data in the Colorado River Basin (Texas)
+    provided by the `Water Quality`_ web site and web service from
+    the `Lower Colorado River Authority`_.
+
+    .. _Lower Colorado River Authority: http://www.lcra.org
+    .. _Water Quality: http://waterquality.lcra.org/
+"""
 from .core import get_sites, get_historical_data, get_recent_data, get_site_info

ulmo/lcra/waterquality/core.py

@@ -1,15 +1,16 @@
 """
     ulmo.lcra.waterquality.core
-    ~~~~~~~~~~~~~~~~~~~~~
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~
     This module provides access to data provided by the `Lower Colorado 
     River Authority`_ `Water Quality`_ web site.
+
     .. _Lower Colorado River Authority: http://www.lcra.org
     .. _Water Quality: http://waterquality.lcra.org/
 """
 from bs4 import BeautifulSoup
 import logging
 from geojson import Point, Feature, FeatureCollection
-#import unicode
+# import unicode
 
 from ulmo import util
 
@@ -51,12 +52,14 @@
 
 def get_sites(source_agency=None):
     """Fetches a list of sites with location and available metadata.
+
     Parameters
     ----------
-    source_agency : LCRA used code of the that collects the data. there
-    are sites whose sources are not listed so this filter may not return
-    all sites of a certain source. see
-    ``source_map``.
+    source_agency : str
+        LCRA used code of the that collects the data. There are sites whose
+        sources are not listed so this filter may not return all sites of a certain source.
+        See ``source_map``.
+
     Returns
     -------
     sites_geojson : geojson FeatureCollection
@@ -82,9 +85,10 @@ def get_sites(source_agency=None):
 
 def get_historical_data(site_code, start=None, end=None, as_dataframe=False):
     """Fetches data for a site at a given date.
+
     Parameters
     ----------
-    site_code: str
+    site_code : str
         The site code to fetch data for. A list of sites can be retrieved with
         ``get_sites()``
     date : ``None`` or date (see :ref:`dates-and-times`)
@@ -96,6 +100,7 @@ def get_historical_data(site_code, start=None, end=None, as_dataframe=False):
         to a dict of gauge variables and values. If ``True`` then the values
         dict will be a pandas.DataFrame object containing the equivalent
         information.
+
     Returns
     -------
     data_dict : dict
@@ -134,7 +139,7 @@ def get_historical_data(site_code, start=None, end=None, as_dataframe=False):
 
     headers = [head.text for head in gridview.findAll('th')]
 
-    #uses \xa0 for blank
+    # uses \xa0 for blank
 
     for row in gridview.findAll('tr'):
         vals = [_parse_val(aux.text) for aux in row.findAll('td')]
@@ -159,6 +164,7 @@ def get_historical_data(site_code, start=None, end=None, as_dataframe=False):
 def get_recent_data(site_code, as_dataframe=False):
     """fetches near real-time instantaneous water quality data for the LCRA
     bay sites.
+
     Parameters
     ----------
     site_code : str
@@ -167,9 +173,11 @@ def get_recent_data(site_code, as_dataframe=False):
         This determines what format values are returned as. If ``False``
         (default), the values will be list of value dicts. If ``True`` then 
         values are returned as pandas.DataFrame.
+
     Returns
     -------
-    list of values or dataframe.
+    list
+        list of values or dataframe.
     """
     if site_code not in real_time_sites.keys():
         log.info('%s is not in the list of LCRA real time salinity sites' %
@@ -242,7 +250,7 @@ def _extract_headers_for_next_request(request):
         if tag_dict.get('value', None) == 'tabular':
             #
             continue
-        #some tags don't have a value and are used w/ JS to toggle a set of checkboxes
+        # some tags don't have a value and are used w/ JS to toggle a set of checkboxes
         payload[tag_dict['name']] = tag_dict.get('value')
     return payload
 
@@ -281,7 +289,7 @@ def _make_next_request(url, previous_request, data):
 
 
 def _parse_val(val):
-    #the &nsbp translates to the following unicode
+    # the &nsbp translates to the following unicode
     if val == u'\xa0':
         return None
     else: