[tune] add more stoppers and stopper documentation (#12750)

* Add new stoppers & docs

* Add tests for maximum iteration stopper and trial plateau stopper

* Update python/ray/tune/stopper.py

Co-authored-by: Richard Liaw <rliaw@berkeley.edu>

* Update doc/source/tune/api_docs/stoppers.rst

Co-authored-by: Richard Liaw <rliaw@berkeley.edu>

* Update doc/source/tune/api_docs/stoppers.rst

Co-authored-by: Richard Liaw <rliaw@berkeley.edu>

* Apply suggestions from code review

* Apply suggestions from code review

* Update python/ray/tune/stopper.py

Co-authored-by: Richard Liaw <rliaw@berkeley.edu>

doc/source/tune/api_docs/execution.rst

@@ -23,14 +23,6 @@ tune.with_parameters
 
 .. autofunction:: ray.tune.with_parameters
 
-.. _tune-stop-ref:
-
-Stopper (tune.Stopper)
-----------------------
-
-.. autoclass:: ray.tune.Stopper
-    :members: __call__, stop_all
-
 .. _tune-sync-config:
 
 tune.SyncConfig

doc/source/tune/api_docs/overview.rst

@@ -21,6 +21,7 @@ on `Github`_.
    suggestion.rst
    schedulers.rst
    sklearn.rst
+   stoppers.rst
    logging.rst
    integration.rst
    internals.rst

doc/source/tune/api_docs/stoppers.rst

@@ -0,0 +1,46 @@
+.. _tune-stoppers:
+
+Stopping mechanisms (tune.stopper)
+==================================
+
+In addition to Trial Schedulers like :ref:`ASHA <tune-scheduler-hyperband>`, where a number of
+trials are stopped if they perform subpar, Ray Tune also supports custom stopping mechanisms to stop trials early. For instance, stopping mechanisms can specify to stop trials when they reached a plateau and the metric
+doesn't change anymore.
+
+Ray Tune comes with several stopping mechanisms out of the box. For custom stopping behavior, you can
+inherit from the :class:`Stopper <ray.tune.Stopper>` class.
+
+Other stopping behaviors are described :ref:`in the user guide <tune-stopping>`.
+
+.. contents::
+    :local:
+    :depth: 1
+
+
+.. _tune-stop-ref:
+
+Stopper (tune.Stopper)
+----------------------
+
+.. autoclass:: ray.tune.Stopper
+    :members: __call__, stop_all
+
+MaximumIterationStopper (tune.stopper.MaximumIterationStopper)
+--------------------------------------------------------------
+
+.. autoclass:: ray.tune.stopper.MaximumIterationStopper
+
+ExperimentPlateauStopper (tune.stopper.ExperimentPlateauStopper)
+----------------------------------------------------------------
+
+.. autoclass:: ray.tune.stopper.ExperimentPlateauStopper
+
+TrialPlateauStopper (tune.stopper.TrialPlateauStopper)
+------------------------------------------------------
+
+.. autoclass:: ray.tune.stopper.TrialPlateauStopper
+
+TimeoutStopper (tune.stopper.TimeoutStopper)
+--------------------------------------------
+
+.. autoclass:: ray.tune.stopper.TimeoutStopper