MNT: Enable Sphinx nitpicky mode

Also clean up a bunch of issues with references found by nitpicky mode.

docs/conf.py

@@ -58,8 +58,15 @@
                        'numpy': ('https://numpy.org/doc/stable/', None),
                        'matplotlib': ('https://matplotlib.org/stable/', None),
                        'requests': ('https://requests.kennethreitz.org/en/latest/', None),
+                       'pandas': ('https://pandas.pydata.org/docs/', None),
                        }
 
+nitpicky = True
+nitpick_ignore = [
+    ('py:class', 'optional'), ('py:class', 'file-like object'), ('py:class', 'iterator')
+]
+nitpick_ignore_regex = [('py:class', r'.*[cC]allable'),]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

examples/ncss/NCSS_Cartopy_Example.py

@@ -55,7 +55,7 @@
 
 ###########################################
 # We now request data from the server using this query. The `NCSS` class handles parsing
-# this NetCDF data (using the `netCDF4` module). If we print out the variable names, we see
+# this NetCDF data (using the ``netCDF4`` module). If we print out the variable names, we see
 # our requested variable, as well as the coordinate variables (needed to properly reference
 # the data).
 data = ncss.get_data(query)

examples/ncss/NCSS_Example.py

@@ -44,7 +44,7 @@
 
 ###########################################
 # We now request data from the server using this query. The `NCSS` class handles parsing
-# this NetCDF data (using the `netCDF4` module). If we print out the variable names,
+# this NetCDF data (using the ``netCDF4`` module). If we print out the variable names,
 # we see our requested variables, as well as a few others (more metadata information)
 data = ncss.get_data(query)
 list(data.variables)

examples/ncss/NCSS_Timeseries_Examples.py

@@ -45,7 +45,7 @@
 
 ###########################################
 # We now request data from the server using this query. The `NCSS` class handles parsing
-# this NetCDF data (using the `netCDF4` module). If we print out the variable names, we
+# this NetCDF data (using the ``netCDF4`` module). If we print out the variable names, we
 # see our requested variables, as well as a few others (more metadata information)
 data = ncss.get_data(query)
 list(data.variables)
@@ -57,7 +57,7 @@
 
 ###########################################
 # The time values are in hours relative to the start of the entire model collection.
-# Fortunately, the `netCDF4` module has a helper function to convert these numbers into
+# Fortunately, the ``netCDF4`` module has a helper function to convert these numbers into
 # Python `datetime` objects. We can see the first 5 element output by the function look
 # reasonable.
 time_vals = num2date(time[:].squeeze(), time.units, only_use_cftime_datetimes=False)

src/siphon/catalog.py

@@ -101,6 +101,7 @@ def filter_time_nearest(self, time, regex=None, strptime=None):
 
         Returns
         -------
+        Dataset
             The value with a time closest to that desired
 
         """
@@ -137,6 +138,7 @@ def filter_time_range(self, start, end, regex=None, strptime=None):
 
         Returns
         -------
+        List[Dataset]
             All values corresponding to times within the specified range
 
         """
@@ -611,7 +613,7 @@ def remote_open(self, mode='b', encoding='ascii', errors='ignore'):
 
         Parameters
         ----------
-        mode : 'b' or 't', optional
+        mode : `'b'` or `'t'`, optional
             Mode with which to open the remote data; 'b' for binary, 't' for text. Defaults
             to 'b'.
 
@@ -625,7 +627,8 @@ def remote_open(self, mode='b', encoding='ascii', errors='ignore'):
 
         Returns
         -------
-        A random access, file-like object
+        fobj : file-like object
+            A random access, file-like object for reading data
 
         """
         fobj = self.access_with_service('HTTPServer')

src/siphon/http_util.py

@@ -96,7 +96,7 @@ def urlopen(self, url, decompress=False, **kwargs):
         url : str
             The URL to request
 
-        kwargs : arbitrary keyword arguments
+        kwargs
             Additional keyword arguments to pass to :meth:`requests.Session.get`.
 
         Returns
@@ -140,14 +140,14 @@ class DataQuery:
 
     This object provides a clear API to formulate a query for data, including
     a spatial query, a time query, and possibly some variables or other parameters.
-    These objects provide a dictionary-like interface, (:meth:`items` and :meth:`__iter__`)
+    These objects provide a dictionary-like interface, (``items`` and ``__iter__``)
     sufficient to be passed to functions expecting a dictionary representing a URL query.
     Instances of this object can also be turned into a string, which will yield a
     properly escaped string for a URL.
     """
 
     def __init__(self):
-        """Construct an empty :class:`DataQuery`."""
+        """Construct an empty class representing a query for data."""
         self.var = set()
         self.time_query = OrderedDict()
         self.spatial_query = OrderedDict()
@@ -163,7 +163,7 @@ def variables(self, *var_names):
 
         Parameters
         ----------
-        var_names : one or more strings
+        var_names : str
             One or more names of variables to request. Use 'all' to request all.
 
         Returns
@@ -183,7 +183,7 @@ def add_query_parameter(self, **kwargs):
 
         Parameters
         ----------
-        kwargs : one or more strings passed as keyword arguments
+        kwargs
             Names and values of parameters to add to the query
 
         Returns
@@ -471,7 +471,7 @@ def get(self, path, params=None):
 
         Raises
         ------
-        HTTPError
+        `~requests.HTTPError`
             If the server returns anything other than a 200 (OK) code
 
         See Also
@@ -506,7 +506,7 @@ def validate_query(self, query):
 
         Parameters
         ----------
-        query : DataQuery (or subclass)
+        query : DataQuery
 
         Returns
         -------

src/siphon/radarserver.py

@@ -30,7 +30,7 @@ def stations(self, *stns):
 
         Parameters
         ----------
-        stns : one or more strings
+        stns : str
             One or more names of variables to request
 
         Returns
@@ -192,7 +192,7 @@ def get_radarserver_datasets(server):
 
     Parameters
     ----------
-    server : string
+    server : str
         The base URL to the THREDDS server
 
     Returns

src/siphon/simplewebservice/acis.py

@@ -37,11 +37,12 @@ def acis_request(method, params):
 
     Returns
     -------
-    A dictionary of data based on the JSON parameters
+    dict[str, Any]
+        A dictionary of data based on the JSON parameters
 
     Raises
     ------
-    :class: `ACIS_API_Exception`
+    `AcisApiException`
         When the API is unable to establish a connection or returns
         unparsable data.
 

src/siphon/simplewebservice/iastate.py

@@ -28,7 +28,7 @@ def request_data(cls, time, site_id, interp_nans=False, **kwargs):
 
         Parameters
         ----------
-        time : datetime
+        time : datetime.datetime
             The date and time of the desired observation.
 
         site_id : str
@@ -61,7 +61,7 @@ def request_all_data(cls, time, pressure=None, **kwargs):
 
         Parameters
         ----------
-        time : datetime
+        time : datetime.datetime
             The date and time of the desired observation.
 
         pressure : float, optional
@@ -85,7 +85,7 @@ def _get_data(self, time, site_id, pressure=None):
 
         Parameters
         ----------
-        time : datetime
+        time : datetime.datetime
             Date and time for which data should be downloaded
         site_id : str
             Site id for which data should be downloaded
@@ -153,7 +153,7 @@ def _get_data_raw(self, time, site_id, pressure=None):
 
         Parameters
         ----------
-        time : datetime
+        time : datetime.datetime
             Date and time for which data should be downloaded
         site_id : str
             Site id for which data should be downloaded

src/siphon/simplewebservice/ndbc.py

@@ -43,7 +43,8 @@ def realtime_observations(cls, buoy, data_type='txt'):
 
         Returns
         -------
-            Raw data string
+        `pandas.DataFrame`
+            Parsed data
 
         """
         endpoint = cls()
@@ -524,6 +525,7 @@ def buoy_data_types(cls, buoy):
 
         Returns
         -------
+        dict[str, str]
             dict of valid file extensions and their descriptions
 
         """
@@ -583,7 +585,8 @@ def raw_buoy_data(cls, buoy, data_type='txt'):
 
         Returns
         -------
-        Raw data string
+        str
+            Raw data string
 
         """
         endpoint = cls()

src/siphon/simplewebservice/wyoming.py

@@ -28,7 +28,7 @@ def request_data(cls, time, site_id, **kwargs):
 
         Parameters
         ----------
-        time : datetime
+        time : datetime.datetime
             The date and time of the desired observation.
 
         site_id : str
@@ -40,7 +40,8 @@ def request_data(cls, time, site_id, **kwargs):
 
         Returns
         -------
-            :class:`pandas.DataFrame` containing the data
+        `pandas.DataFrame`
+            Parsed data
 
         """
         endpoint = cls()
@@ -52,7 +53,7 @@ def _get_data(self, time, site_id):
 
         Parameters
         ----------
-        time : datetime
+        time : datetime.datetime
             The date and time of the desired observation.
 
         site_id : str
@@ -61,7 +62,7 @@ def _get_data(self, time, site_id):
 
         Returns
         -------
-            :class:`pandas.DataFrame` containing the data
+        `pandas.DataFrame`
 
         """
         raw_data = self._get_data_raw(time, site_id)
@@ -130,14 +131,15 @@ def _get_data_raw(self, time, site_id):
 
         Parameters
         ----------
-        time : datetime
+        time : datetime.datetime
             Date and time for which data should be downloaded
         site_id : str
             Site id for which data should be downloaded
 
         Returns
         -------
-        text of the server response
+        str
+            text of the server response
 
         """
         path = ('?region=naconf&TYPE=TEXT%3ALIST'