docs: added references in each docstring to where the function is used in the tutorials. Added and fixed multiple docs references. Added changelogs in docstrings with versionchanged/versionadded directives to outline major changes. Added optional label to multiple args in docstrings

ft: re-added xlabel_rotation for comparison_plots
fix: typos in docstrings
build-sphinx: rewrite "make clean" directive, to effectively delete generated sphinx-gallery and sphinx-autodocs material.

Author: pabloitu

csep/__init__.py

@@ -333,7 +333,7 @@ def query_gns(start_time, end_time,  min_magnitude=2.950,
         verbose (bool): print catalog summary statistics
 
     Returns:
-        :class:`csep.core.catalogs.CSEPCatalog
+        :class:`csep.core.catalogs.CSEPCatalog`
     """
 
     # Timezone should be in UTC

csep/utils/plots.py

@@ -17,7 +17,8 @@ livehtml:
 
 clean:
 	rm -rf $(BUILDDIR)/*
-	rm -rf auto_examples/
+	rm -rf tutorials/*
+	rm -rf reference/generated
 
 .PHONY: help Makefile
 

docs/Makefile

@@ -91,7 +91,7 @@ statistics from these catalogs and compare them against one another.
 
 We provide four statistics that probe fundamental aspects of the earthquake forecasts. Please see
 :ref:`Savran et al., 2020<savran-2020>` for a complete description of the individual tests. For the implementation
-details please follow the links below and see the :ref:`example<catalog-forecast-evaluation>` for catalog-based
+details please follow the links below and see the :ref:`Example <tutorial-catalog-forecast-evaluation>` for catalog-based
 forecast evaluation for an end-to-end walk through.
 
 .. automodule:: csep.core.catalog_evaluations

docs/concepts/evaluations.rst

@@ -129,7 +129,7 @@ Working with catalog-based forecasts
 
 .. autosummary:: csep.core.forecasts.CatalogForecast
 
-Please see visit :ref:`this<catalog-forecast-evaluation>` example for an end-to-end tutorial on how to evaluate a catalog-based
+Please see visit :ref:`this Example <tutorial-catalog-forecast-evaluation>` 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>`__.
 

docs/concepts/forecasts.rst

@@ -6,8 +6,6 @@ Regions
 
 .. automodule:: csep.core.regions
    :no-index:
-.. automodule:: csep.utils.basic_types
-   :no-index:
 
 PyCSEP includes commonly used CSEP testing regions and classes that facilitate working with gridded data sets. This
 module is early in development and will be a focus of future development.

docs/concepts/regions.rst

@@ -104,6 +104,8 @@ examples use the Helmstetter et al (2007) smoothed seismicity forecast
     Found 24 events in the ComCat catalog.
 
 
+.. _theory-consistency-tests:
+
 Consistency tests
 ~~~~~~~~~~~~~~~~~
 
@@ -655,6 +657,8 @@ case, the model with aftershocks performs statistically worse than the
 benchmark model. We note that this comparison is used for demonstation
 purposes only.
 
+.. _theory-catalog-forecasts:
+
 Catalog-based forecast tests
 ----------------------------
 

docs/getting_started/theory.rst

@@ -100,6 +100,9 @@
 
 
 ####################################################################################################################################
+#
+# .. _tutorial-catalog-filtering-plot:
+#
 # Plot catalog
 # -------------
 #

examples/tutorials/catalog_filtering.py

@@ -102,6 +102,9 @@
 comcat_catalog.plot(show=True)
 
 ####################################################################################################################################
+#
+# .. _catalog-forecast-evaluation-exploratory:
+#
 # Exploratory visualizations
 # --------------------------
 #
@@ -126,6 +129,9 @@
 number_test_result = catalog_evaluations.number_test(forecast, comcat_catalog)
 
 ####################################################################################################################################
+#
+# .. _catalog-forecast-evaluation-plot:
+#
 # Plot number test result
 # -----------------------
 #

examples/tutorials/catalog_forecast_evaluation.py

@@ -93,6 +93,9 @@
 csep.write_json(spatial_test_result, 'example_spatial_test.json')
 
 ####################################################################################################################################
+#
+# .. _grid-forecast-evaluation-plot:
+#
 # Plot spatial test results
 # -------------------------
 #
@@ -105,6 +108,9 @@
 
 
 ####################################################################################################################################
+#
+# .. _grid-forecast-evaluation-plot-comparison:
+#
 # Performing a comparative test
 # -----------------------------
 #
@@ -126,6 +132,9 @@
 
 
 ####################################################################################################################################
+#
+# .. _grid-forecast-evaluation-concentration-roc:
+#
 # Plot ROC Curves
 # ---------------
 #
@@ -149,6 +158,9 @@
 
 
 ####################################################################################################################################
+#
+# .. _grid-forecast-evaluation-roc-and-molchan:
+#
 # Plot ROC and Molchan curves using the alarm-based approach
 # ----------------------------------------------------------
 

examples/tutorials/gridded_forecast_evaluation.py

@@ -18,8 +18,11 @@
 """
 
 ################################################################################################################
-# Example 1: Spatial dataset plot arguments
-# -----------------------------------------
+#
+# .. _tutorial-plot-customizations-ex1:
+#
+# Example 1: Customizing Gridded Dataset Plot
+# -------------------------------------------
 
 ####################################################################################################################################
 # **Load required libraries**
@@ -49,10 +52,10 @@
 # * Assign a title
 # * Set labels to the geographic axes
 # * Draw country borders
-# * Set a linewidth of 0.5 to country border
-# * Assign ``'rainbow'`` as the colormap. Possible values from ``matplotlib.cm`` library
+# * Set a linewidth of 1.5 to country border
+# * Assign ``'rainbow'`` as the colormap. Possible values from :mod:`matplotlib.cm` library
 # * Defines 0.8 for an exponential transparency function (default is 0 for constant alpha, whereas 1 for linear).
-# * An object cartopy.crs.Projection() is passed as Projection to the map
+# * An object :class:`cartopy.crs.Projection` (in this case :class:`cartopy.crs.Mercator`) is passed to the map
 #
 # The complete description of plot arguments can be found in :func:`csep.utils.plots.plot_gridded_dataset`
 #
@@ -70,6 +73,9 @@
                    show=True)
 
 ####################################################################################################################################
+#
+# .. _tutorial-plot-customizations-ex2:
+#
 # Example 2: Plot a global forecast and a selected magnitude bin range
 # --------------------------------------------------------------------
 #
@@ -105,7 +111,7 @@
 ####################################################################################################################################
 # **Plotting the dataset**
 #
-# To plot a global forecast, we must assign the option ``set_global=True``, which is required by :ref:`cartopy` to handle
+# To plot a global forecast, we must assign the option ``set_global=True``, which is required by :mod:`cartopy` to handle
 # internally the extent of the plot. We can further customize the plot using the required arguments from :func:`~csep.utils.plots.plot_gridded_dataset`
 #
 
@@ -131,6 +137,9 @@
 
 
 ####################################################################################################################################
+#
+# .. _tutorial-plot-customizations-ex3:
+#
 # Example 3: Plot a catalog with a custom basemap
 # -----------------------------------------------
 
@@ -178,8 +187,15 @@
 
 ax = catalog.plot(show=True, **plot_args)
 
+####################################################################################################################################
+# Alternatively, it can be plotted using the :func:`csep.utils.plots.plot_catalog` function
+
+plots.plot_catalog(catalog=catalog, show=True, **plot_args)
 
 ####################################################################################################################################
+#
+# .. _tutorial-plot-customizations-ex4:
+#
 # Example 4: Plot composition
 # -----------------------------------------------
 #
@@ -205,6 +221,7 @@
 # Plot the basemap alone by using :func:`csep.utils.plots.plot_basemap`. Do not set ``show=True`` and store the returned ``ax`` object to
 # start the composite plot
 
+# Start the base plot
 ax = plots.plot_basemap(figsize=(8, 8),
                         projection=cartopy.crs.AlbersEqualArea(central_longitude=-120.),
                         extent=forecast.region.get_bbox(),
@@ -217,9 +234,12 @@
 ax = forecast.plot(colormap='PuBu_r', alpha_exp=0.5, ax=ax)
 
 # Use show=True to finalize the composite.
-catalog.plot(markercolor='darkred', ax=ax, show=True)
+plots.plot_catalog(catalog=catalog, markercolor='darkred', ax=ax, show=True)
 
 ####################################################################################################################################
+#
+# .. _tutorial-plot-customizations-ex5:
+#
 # Example 5: Plot multiple evaluation results
 # -------------------------------------------
 

examples/tutorials/plot_customizations.py

@@ -1,6 +1,6 @@
 """
 
-.. tutorial-handling-grid-forecast:
+.. _tutorial-handling-grid-forecast:
 
 Handling Grid-based Forecasts
 =============================
@@ -42,6 +42,9 @@
                                       name='helmstetter_mainshock')
 
 ####################################################################################################################################
+#
+# .. _tutorial-handling-grid-forecast-plot:
+#
 # Plot forecast
 # -------------
 #

examples/tutorials/plot_gridded_forecast.py

@@ -186,6 +186,9 @@
 
 
 ####################################################################################################################################
+#
+# .. _quadtree_gridded-forecast-evaluation-plot:
+#
 # Plot spatial test results
 # -------------------------
 #

examples/tutorials/quadtree_gridded_forecast_evaluation.py

@@ -68,6 +68,9 @@
 
 
 ####################################################################################################################################
+#
+# .. _tutorial-working-catalog-forecasts-plot:
+#
 # Plot expected event counts
 # --------------------------
 #