ci: added plots.py to coverage

ft: added helper to issue deprecation warning when plot_args is passed. Added typehinting overload to legacy wrappers, so IDEs can detect signature/docstrings.
fix: avoid drawing basemap when an ax is passed to plot_catalog and plot_gridded_dataset.  modified .plot methods to be consistent with new plot functionality
docs: remove plots.rst

Author: pabloitu

.coveragerc

@@ -5,7 +5,6 @@ omit =
     tests/*
     docs/*
     examples/*
-    csep/utils/plots.py
     csep/utils/constants.py
     csep/utils/datasets.py
     csep/utils/documents.py

csep/core/catalogs.py

@@ -841,40 +841,41 @@ def b_positive(self):
         pass
 
     def plot(self, ax=None, show=False, extent=None, set_global=False, **kwargs):
-        """ Plot catalog according to plate-carree projection. See
-        https://docs.cseptesting.org/reference/generated/csep.utils.plots.plot_catalog.html for
-        a description of keyword arguments.
+        """ Plots the catalog epicenters.
+
+        See :func:`csep.utils.plots.plot_catalog` for a description of keyword arguments.
 
         Args:
-            ax (`matplotlib.pyplot.axes`): Previous axes onto which catalog can be drawn
-            show (bool): if true, show the figure. this call is blocking.
+            ax (matplotlib.pyplot.axes): Previous axes onto which catalog can be drawn
+            show (bool): If True, shows the figure.
             extent (list): Force an extent [lon_min, lon_max, lat_min, lat_max]
             set_global (bool): Whether to plot using a global projection
+            **kwargs (dict): Keyword arguments passed to
+                :func:`csep.utils.plots.plot_catalog`
 
         Returns:
             axes: matplotlib.Axes.axes
         """
 
         # no mutable function arguments
-        plot_args_default = {
+        plot_args = {
              'basemap': kwargs.pop('basemap', 'ESRI_terrain') if ax is None else None
         }
 
         # Plot the region border (if it exists) by default
         try:
             # This will throw error if catalog does not have region
             _ = self.region.num_nodes
-            plot_args_default['region_border'] = True
+            plot_args['region_border'] = True
         except AttributeError:
             pass
 
-        plot_args = kwargs.get('plot_args', {})
-        plot_args_default.update(plot_args)
-        plot_args_default.update(kwargs)
+        plot_args.update(kwargs.get('plot_args', {}))
+        plot_args.update(kwargs)
 
         # this call requires internet connection and basemap
         ax = plot_catalog(self, ax=ax, show=show, extent=extent,
-                          set_global=set_global, **plot_args_default)
+                          set_global=set_global, **plot_args)
         return ax
 
     def plot_magnitude_versus_time(self, ax=None, show=False, **kwargs):

csep/core/forecasts.py

@@ -434,16 +434,25 @@ def load_ascii(cls, ascii_fname, start_date=None, end_date=None, name=None, swap
 
     def plot(self, ax=None, show=False, log=True, extent=None, set_global=False, plot_args=None,
              **kwargs):
-        """ Plot gridded forecast according to plate-carree projection
+        """ Plot the spatial rate of the forecast
+
+        See :func:`csep.utils.plots.plot_gridded_dataset` for a detailed description of the
+        keyword arguments.
 
         Args:
-            show (bool): if true, show the figure. this call is blocking.
-            plot_args (optional/dict): dictionary containing plotting arguments for making figures
+            ax (`matplotlib.pyplot.axes`): Previous axes onto which catalog can be drawn
+            show (bool): If True, shows the figure.
+            log (bool): If True, plots the base-10 logarithm of the spatial rates
+            extent (list): Force an extent [lon_min, lon_max, lat_min, lat_max]
+            set_global (bool): Whether to plot using a global projection
+            **kwargs (dict): Keyword arguments passed to
+                :func:`csep.utils.plots.plot_gridded_dataset`
 
         Returns:
             axes: matplotlib.Axes.axes
         """
-        # no mutable function arguments
+
+
         if self.start_time is None or self.end_time is None:
             time = 'forecast period'
         else: