Merge pull request #2569 from jcoughlin11/clear_annotations

annotate_clear -> clear_annotations

doc/source/cookbook/find_clumps.py

@@ -55,7 +55,7 @@
 # Clump annotation can also be done with the reloaded clump dataset.
 
 # Remove the original clump annotation
-prj.annotate_clear()
+prj.clear_annotations()
 
 # Get the leaves and add the callback.
 leaf_clumps_reloaded = cds.leaves

doc/source/reference/api/api.rst

@@ -676,6 +676,7 @@ See also :ref:`callbacks`.
 .. autosummary::
 
    ~yt.visualization.plot_window.PWViewerMPL.annotate_clear
+   ~yt.visualization.plot_window.PWViewerMPL.clear_annotations
    ~yt.visualization.plot_modifications.ArrowCallback
    ~yt.visualization.plot_modifications.CellEdgesCallback
    ~yt.visualization.plot_modifications.ClumpContourCallback

doc/source/visualizing/callbacks.rst

@@ -30,7 +30,7 @@ the plot object.  All of the callbacks listed below are available via
 similar ``annotate_`` functions.
 
 To clear one or more annotations from an existing plot, see the
-:ref:`annotate_clear() function <annotate-clear>`.
+:ref:`clear_annotations() function <clear-annotations>`.
 
 For a brief demonstration of a few of these callbacks in action together,
 see the cookbook recipe: :ref:`annotations-recipe`.
@@ -120,12 +120,12 @@ Available Callbacks
 
 The underlying functions are more thoroughly documented in :ref:`callback-api`.
 
-.. _annotate-clear:
+.. _clear-annotations:
 
 Clear Callbacks (Some or All)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. function:: annotate_clear(index=None)
+.. function:: clear_annotations(index=None)
 
     This function will clear previous annotations (callbacks) in the plot.
     If no index is provided, it will clear all annotations to the plot.
@@ -142,7 +142,7 @@ Clear Callbacks (Some or All)
     p.annotate_timestamp()
 
     # Oops, I didn't want any of that.
-    p.annotate_clear()
+    p.clear_annotations()
     p.save()
 
 .. _annotate-list:

yt/visualization/plot_window.py

@@ -27,7 +27,8 @@
     YTSpatialPlotDataset
 from yt.funcs import \
     mylog, iterable, ensure_list, \
-    fix_axis, fix_unitary, obj_length
+    fix_axis, fix_unitary, obj_length, \
+    issue_deprecation_warning
 from yt.units.unit_object import \
     Unit
 from yt.units.unit_registry import \
@@ -1125,12 +1126,30 @@ def setup_callbacks(self):
             callback.__doc__ = CallbackMaker.__doc__
             self.__dict__['annotate_'+cbname] = types.MethodType(callback,self)
 
-    @invalidate_plot
     def annotate_clear(self, index=None):
         """
         Clear callbacks from the plot.  If index is not set, clear all
         callbacks.  If index is set, clear that index (ie 0 is the first one
         created, 1 is the 2nd one created, -1 is the last one created, etc.)
+
+        .. note::
+
+            Deprecated in favor of `clear_annotations`.
+
+        See Also
+        --------
+        :py:meth:`yt.visualization.plot_window.PWViewerMPL.clear_annotations`
+        """
+        issue_deprecation_warning("\"annotate_clear\" has been deprecated"
+            " in favor of \"clear_annotations\". Using \"clear_annotations\".")
+        self.clear_annotations(index=index)
+
+    @invalidate_plot
+    def clear_annotations(self, index=None):
+        """
+        Clear callbacks from the plot.  If index is not set, clear all
+        callbacks.  If index is set, clear that index (ie 0 is the first one
+        created, 1 is the 2nd one created, -1 is the last one created, etc.)
         """
         if index is None:
             self._callbacks = []