Fixed documentation errors and warnings.

csep/__init__.py

@@ -214,7 +214,7 @@ def query_comcat(start_time, end_time, min_magnitude=2.50,
         verbose (bool): print catalog summary statistics
 
     Returns:
-        :class:`csep.core.catalogs.CSEPCatalog
+        :class:`csep.core.catalogs.CSEPCatalog`
     """
 
     # Timezone should be in UTC
@@ -273,7 +273,7 @@ def query_bsi(start_time, end_time, min_magnitude=2.50,
         verbose (bool): print catalog summary statistics
 
     Returns:
-        :class:`csep.core.catalogs.CSEPCatalog
+        :class:`csep.core.catalogs.CSEPCatalog`
     """
 
     # Timezone should be in UTC
@@ -429,8 +429,8 @@ class with the region and magnitude members correctly assigned.
     Args:
         fname (str): path of grid based forecast
         loader (func): function to load forecast in bespoke format needs to return :class:`csep.core.forecasts.GriddedForecast`
-                       and first argument should be required and the filename of the forecast to load
-                       called as loader(func, **kwargs).
+                       and should be called with the filename of the forecast to load as the first argument,
+                       followed by additional keyword arguments, like this: ``loader(func, **kwargs)``.
 
         **kwargs: passed into loader function
 

csep/core/forecasts.py

@@ -363,7 +363,7 @@ def from_custom(cls, func, func_args=(), **kwargs):
         """ Creates MarkedGriddedDataSet class from custom parsing function.
 
         Args:
-            func (callable): function will be called as func(*func_args).
+            func (callable): function will be called as func(func_args).
             func_args (tuple): arguments to pass to func
             **kwargs: keyword arguments to pass to the GriddedForecast class constructor.
 
@@ -756,6 +756,7 @@ def load_ascii(cls, fname, **kwargs):
             fname (str): path to file or directory containing forecast files
 
         Returns:
-              :class:`csep.core.forecasts.CatalogForecast
+              :class:`csep.core.forecasts.CatalogForecast`
+
         """
         raise NotImplementedError("load_ascii is not implemented!")

csep/utils/comcat.py

@@ -80,110 +80,89 @@ def search(starttime=None,
            host=None,
            enable_limit=False,
            verbose=False):
-    """Search the ComCat database for events matching input criteria.
+    """
+
+    Search the ComCat database for events matching input criteria.
     This search function is a wrapper around the ComCat Web API described here:
     https://earthquake.usgs.gov/fdsnws/event/1/
     Some of the search parameters described there are NOT implemented here, usually because they do not
     apply to GeoJSON search results, which we are getting here and parsing into Python data structures.
     This function returns a list of SummaryEvent objects, described elsewhere in this package.
-    Usage:
-      TODO: Show usage information.
+
     Args:
-        starttime (datetime):
-            Python datetime - Limit to events on or after the specified start time.
-        endtime (datetime):
-            Python datetime - Limit to events on or before the specified end time.
-        updatedafter (datetime):
-           Python datetime - Limit to events updated after the specified time.
-        minlatitude (float):
-            Limit to events with a latitude larger than the specified minimum.
-        maxlatitude (float):
-            Limit to events with a latitude smaller than the specified maximum.
-        minlongitude (float):
-            Limit to events with a longitude larger than the specified minimum.
-        maxlongitude (float):
-            Limit to events with a longitude smaller than the specified maximum.
-        latitude (float):
-            Specify the latitude to be used for a radius search.
-        longitude (float):
-            Specify the longitude to be used for a radius search.
-        maxradiuskm (float):
-            Limit to events within the specified maximum number of kilometers
+        starttime (datetime): Limit to events on or after the specified start time.
+        endtime (datetime): Limit to events on or before the specified end time.
+        updatedafter (datetime): Limit to events updated after the specified time.
+        minlatitude (float): Limit to events with a latitude larger than the specified minimum.
+        maxlatitude (float): Limit to events with a latitude smaller than the specified maximum.
+        minlongitude (float): Limit to events with a longitude larger than the specified minimum.
+        maxlongitude (float): Limit to events with a longitude smaller than the specified maximum.
+        latitude (float): Specify the latitude to be used for a radius search.
+        longitude (float): Specify the longitude to be used for a radius search.
+        maxradiuskm (float): Limit to events within the specified maximum number of kilometers
             from the geographic point defined by the latitude and longitude parameters.
-        maxradius (float):
-            Limit to events within the specified maximum number of degrees
+        maxradius (float): Limit to events within the specified maximum number of degrees
             from the geographic point defined by the latitude and longitude parameters.
-        catalog (str):
-            Limit to events from a specified catalog.
-        contributor (str):
-            Limit to events contributed by a specified contributor.
-        limit (int):
-            Limit the results to the specified number of events.
-             NOTE, this will be throttled by this Python API to the supported Web API limit of 20,000.
-        maxdepth (float):
-            Limit to events with depth less than the specified maximum.
-        maxmagnitude (float):
-            Limit to events with a magnitude smaller than the specified maximum.
-        mindepth (float):
-            Limit to events with depth more than the specified minimum.
-        minmagnitude (float):
-            Limit to events with a magnitude larger than the specified minimum.
-        offset (int):
-            Return results starting at the event count specified, starting at 1.
-        orderby (str):
-            Order the results. The allowed values are:
-            - time order by origin descending time
-            - time-asc order by origin ascending time
-            - magnitude order by descending magnitude
-            - magnitude-asc order by ascending magnitude
-        alertlevel (str):
-            Limit to events with a specific PAGER alert level. The allowed values are:
-              - green Limit to events with PAGER alert level "green".
-              - yellow Limit to events with PAGER alert level "yellow".
-              - orange Limit to events with PAGER alert level "orange".
-              - red Limit to events with PAGER alert level "red".
-        eventtype (str):
-            Limit to events of a specific type. NOTE: "earthquake" will filter non-earthquake events.
-        maxcdi (float):
-            Maximum value for Maximum Community Determined Intensity reported by DYFI.
-        maxgap (float):
-            Limit to events with no more than this azimuthal gap.
-        maxmmi (float):
-            Maximum value for Maximum Modified Mercalli Intensity reported by ShakeMap.
-        maxsig (float):
-            Limit to events with no more than this significance.
-        mincdi (float):
-            Minimum value for Maximum Community Determined Intensity reported by DYFI.
-        minfelt (int):
-            Limit to events with this many DYFI responses.
-        mingap (float):
-            Limit to events with no less than this azimuthal gap.
-        minsig (float):
-            Limit to events with no less than this significance.
-        producttype (str):
-            Limit to events that have this type of product associated. Example producttypes:
-               - moment-tensor
-               - focal-mechanism
-               - shakemap
-               - losspager
-               - dyfi
-        productcode (str):
-              Return the event that is associated with the productcode.
-              The event will be returned even if the productcode is not
-              the preferred code for the event. Example productcodes:
-               - nn00458749
-               - at00ndf1fr
-        reviewstatus (str):
-            Limit to events with a specific review status. The different review statuses are:
-                - automatic Limit to events with review status "automatic".
-                - reviewed Limit to events with review status "reviewed".
-        host (str):
-            Replace default ComCat host (earthquake.usgs.gov) with a custom host.
+        catalog (str): Limit to events from a specified catalog.
+        contributor (str): Limit to events contributed by a specified contributor.
+        limit (int): Limit the results to the specified number of events.
+            NOTE: this will be throttled by this Python API to the supported Web API limit of 20,000.
+        maxdepth (float): Limit to events with depth less than the specified maximum.
+        maxmagnitude (float): Limit to events with a magnitude smaller than the specified maximum.
+        mindepth (float): Limit to events with depth more than the specified minimum.
+        minmagnitude (float): Limit to events with a magnitude larger than the specified minimum.
+        offset (int): Return results starting at the event count specified, starting at 1.
+        orderby (str): Order the results. The allowed values are:
+
+            - `time`: order by origin descending time
+            - `time-asc`: order by origin ascending time
+            - `magnitude`: order by descending magnitude
+            - `magnitude-asc`: order by ascending magnitude
+
+        alertlevel (str): Limit to events with a specific PAGER alert level. The allowed values are:
+
+            - `green`: Limit to events with PAGER alert level "green".
+            - `yellow`: Limit to events with PAGER alert level "yellow".
+            - `orange`: Limit to events with PAGER alert level "orange".
+            - `red`: Limit to events with PAGER alert level "red".
+
+        eventtype (str): Limit to events of a specific type. NOTE: "earthquake" will filter non-earthquake events.
+        maxcdi (float): Maximum value for Maximum Community Determined Intensity reported by DYFI.
+        maxgap (float): Limit to events with no more than this azimuthal gap.
+        maxmmi (float): Maximum value for Maximum Modified Mercalli Intensity reported by ShakeMap.
+        maxsig (float): Limit to events with no more than this significance.
+        mincdi (float): Minimum value for Maximum Community Determined Intensity reported by DYFI.
+        minfelt (int): Limit to events with this many DYFI responses.
+        mingap (float): Limit to events with no less than this azimuthal gap.
+        minsig (float): Limit to events with no less than this significance.
+        producttype (str): Limit to events that have this type of product associated. Example product types:
+
+            - `moment-tensor`
+            - `focal-mechanism`
+            - `shakemap`
+            - `losspager`
+            - `dyfi`
+
+        productcode (str): Return the event that is associated with the product code.
+            The event will be returned even if the product code is not
+            the preferred code for the event. Example product codes:
+
+            - `nn00458749`
+            - `at00ndf1fr`
+
+        reviewstatus (str): Limit to events with a specific review status. The different review statuses are:
+
+            - `automatic`: Limit to events with review status "automatic".
+            - `reviewed`: Limit to events with review status "reviewed".
+
+        host (str): Replace default ComCat host (earthquake.usgs.gov) with a custom host.
         enable_limit (bool): Enable 20,000 event search limit. Will turn off searching
             in segments, which is meant to safely avoid that limit.
             Use only when you are certain your search will be small.
+
     Returns:
         list: List of SummaryEvent() objects.
+
     """
     # getting the inputargs must be the first line of the method!
     inputargs = locals().copy()

docs/concepts/catalogs.rst

@@ -187,7 +187,7 @@ Once you have a function that returns an eventlist, you can create the catalog o
     eventlist = my_custom_web_loader(...)
     catalog = csep.catalogs.CSEPCatalog(data=eventlist, **kwargs)
 
-The **kwargs represents any other keyword argument that can be passed to
+The `**kwargs` represents any other keyword argument that can be passed to
 :class:`CSEPCatalog<csep.core.catalogs.CSEPCatalog>`. This could be the ``catalog_id`` or the
 :class:`CartesianGrid2D<csep.core.regions.CartesianGrid2D>`.
 
@@ -216,6 +216,7 @@ provide some getter methods to access the essential catalog data. These return a
 ``dtype`` defined by the class.
 
 .. automodule:: csep.core.catalogs
+   :no-index:
 
 The following functions return :class:`numpy.ndarrays<numpy.ndarray>` of the catalog information.
 
@@ -287,7 +288,7 @@ object to filter events using the data type.
 
 The filter function can accept a string or a list of filter statements. If the function is called without any arguments
 the function looks to use the ``catalog.filters`` member. This can be provided during class instantiation or bound
-to the class afterward. :ref:`Here<tutorial-catalog-filtering>` is complete example of how to filter a catalog
+to the class afterward. :ref:`Here <tutorial-catalog-filtering>` is complete example of how to filter a catalog
 using the filtering strings.
 
 Filtering events in space

docs/concepts/evaluations.rst

@@ -1,6 +1,7 @@
 .. _evaluation-reference:
 
 .. automodule:: csep.core.poisson_evaluations
+   :no-index:
 
 ###########
 Evaluations
@@ -94,6 +95,7 @@ details please follow the links below and see the :ref:`example<catalog-forecast
 forecast evaluation for an end-to-end walk through.
 
 .. automodule:: csep.core.catalog_evaluations
+   :no-index:
 
 Consistency tests
 =================

docs/concepts/forecasts.rst

@@ -56,7 +56,7 @@ The default file format of a gridded-forecast is a tab delimited ASCII file with
 
 Each row represents a single space-magnitude bin and the entire forecast file contains the rate for a specified
 time-horizon. An example of a gridded forecast for the RELM testing region can be found
-`here <https://github.com/SCECcode/csep2/blob/dev/csep/artifacts/ExampleForecasts/GriddedForecasts/helmstetter_et_al.hkj.aftershock-fromXML.dat>`_.
+`here <https://github.com/SCECcode/csep2/blob/dev/csep/artifacts/ExampleForecasts/GriddedForecasts/helmstetter_et_al.hkj.aftershock-fromXML.dat>`__.
 
 
 The coordinates (LON, LAT, DEPTH, MAG) describe the independent space-magnitude region of the forecast. The lower
@@ -79,7 +79,7 @@ the forecast into the appropriate format in the first place. This function has n
 expected data.
 
 .. automethod:: csep.core.forecasts.GriddedForecast.from_custom
-
+   :no-index:
 
 Working with quadtree-gridded forecasts
 ##############################################
@@ -131,15 +131,15 @@ Working with catalog-based forecasts
 
 Please see visit :ref:`this<catalog-forecast-evaluation>` example for an end-to-end tutorial on how to evaluate a catalog-based
 earthquake forecast. An example of a catalog-based forecast stored in the default pyCSEP format can be found
-`here <https://github.com/SCECcode/pycsep/blob/dev/csep/artifacts/ExampleForecasts/CatalogForecasts/ucerf3-landers_1992-06-28T11-57-34-14.csv>`_.
+`here <https://github.com/SCECcode/pycsep/blob/dev/csep/artifacts/ExampleForecasts/CatalogForecasts/ucerf3-landers_1992-06-28T11-57-34-14.csv>`__.
 
 
 The standard format for catalog-based forecasts a comma separated value ASCII format. This format was chosen to be
 human-readable and easy to implement in all programming languages. Information about the format is shown below.
 
 .. note::
     Custom formats can be supported by writing a custom function or sub-classing the
-    :ref:`AbstractBaseCatalog<csep.core.forecasts.AbstractBaseCatalog>`.
+    :class:`AbstractBaseCatalog <csep.core.catalogs.AbstractBaseCatalog>`.
 
 The event format matches the follow specfication: ::