[tune] Update API Reference Page (#7671)

* widerdocs

* init

* docs

* fix

* moveit

* mix

* better_docs

* remove

* Apply suggestions from code review

Co-Authored-By: Sven Mika <sven@anyscale.io>

Co-authored-by: Sven Mika <sven@anyscale.io>

python/ray/tune/suggest/ax.py

@@ -40,13 +40,20 @@ class AxSearch(SuggestionAlgorithm):
             trial results in the optimization process.
 
 
-    Example:
-        >>> parameters = [
-        >>>     {"name": "x1", "type": "range", "bounds": [0.0, 1.0]},
-        >>>     {"name": "x2", "type": "range", "bounds": [0.0, 1.0]},
-        >>> ]
-        >>> algo = AxSearch(parameters=parameters,
-        >>>     objective_name="hartmann6", max_concurrent=4)
+    .. code-block:: python
+
+        from ray import tune
+        from ray.tune.suggest.ax import AxSearch
+
+        parameters = [
+            {"name": "x1", "type": "range", "bounds": [0.0, 1.0]},
+            {"name": "x2", "type": "range", "bounds": [0.0, 1.0]},
+        ]
+
+        algo = AxSearch(parameters=parameters,
+            objective_name="hartmann6", max_concurrent=4)
+        tune.run(my_func, algo=algo)
+
     """
 
     def __init__(self, ax_client, max_concurrent=10, mode="max", **kwargs):

python/ray/tune/suggest/basic_variant.py

@@ -14,18 +14,35 @@ class BasicVariantGenerator(SearchAlgorithm):
 
     See also: `ray.tune.suggest.variant_generator`.
 
-    Example:
-        >>> searcher = BasicVariantGenerator()
-        >>> searcher.add_configurations({"experiment": { ... }})
-        >>> list_of_trials = searcher.next_trials()
-        >>> searcher.is_finished == True
+
+    Parameters:
+        shuffle (bool): Shuffles the generated list of configurations.
+
+    User API:
+
+    .. code-block:: python
+
+        from ray import tune
+        from ray.tune.suggest import BasicVariantGenerator
+
+        searcher = BasicVariantGenerator()
+        tune.run(my_trainable_func, algo=searcher)
+
+    Internal API:
+
+    .. code-block:: python
+
+        from ray.tune.suggest import BasicVariantGenerator
+
+        searcher = BasicVariantGenerator()
+        searcher.add_configurations({"experiment": { ... }})
+        list_of_trials = searcher.next_trials()
+        searcher.is_finished == True
     """
 
     def __init__(self, shuffle=False):
         """Initializes the Variant Generator.
 
-        Arguments:
-            shuffle (bool): Shuffles the generated list of configurations.
         """
         self._parser = make_parser()
         self._trial_generator = []

python/ray/tune/suggest/bayesopt.py

@@ -15,7 +15,7 @@ class BayesOptSearch(SuggestionAlgorithm):
     """A wrapper around BayesOpt to provide trial suggestions.
 
     Requires BayesOpt to be installed. You can install BayesOpt with the
-    command: `pip install bayesian-optimization`.
+    command: ``pip install bayesian-optimization``.
 
     Parameters:
         space (dict): Continuous search space. Parameters will be sampled from
@@ -32,14 +32,22 @@ class BayesOptSearch(SuggestionAlgorithm):
         use_early_stopped_trials (bool): Whether to use early terminated
             trial results in the optimization process.
 
-    Example:
-        >>> space = {
-        >>>     'width': (0, 20),
-        >>>     'height': (-100, 100),
-        >>> }
-        >>> algo = BayesOptSearch(
-        >>>     space, max_concurrent=4, metric="mean_loss", mode="min")
+    .. code-block:: python
+
+        from ray import tune
+        from ray.tune.suggest.bayesopt import BayesOptSearch
+
+        space = {
+            'width': (0, 20),
+            'height': (-100, 100),
+        }
+        algo = BayesOptSearch(
+            space, max_concurrent=4, metric="mean_loss", mode="min")
+
+        tune.run(my_func, algo=algo)
     """
+    # bayes_opt.BayesianOptimization: Optimization object
+    optimizer = None
 
     def __init__(self,
                  space,

python/ray/tune/suggest/bohb.py

@@ -22,7 +22,7 @@ class TuneBOHB(SuggestionAlgorithm):
 
 
     Requires HpBandSter and ConfigSpace to be installed. You can install
-    HpBandSter and ConfigSpace with: `pip install hpbandster ConfigSpace`.
+    HpBandSter and ConfigSpace with: ``pip install hpbandster ConfigSpace``.
 
     This should be used in conjunction with HyperBandForBOHB.
 
@@ -38,23 +38,28 @@ class TuneBOHB(SuggestionAlgorithm):
             minimizing or maximizing the metric attribute.
 
     Example:
-        >>> import ConfigSpace as CS
-        >>> config_space = CS.ConfigurationSpace()
-        >>> config_space.add_hyperparameter(
-                CS.UniformFloatHyperparameter('width', lower=0, upper=20))
-        >>> config_space.add_hyperparameter(
-                CS.UniformFloatHyperparameter('height', lower=-100, upper=100))
-        >>> config_space.add_hyperparameter(
-                CS.CategoricalHyperparameter(
-                    name='activation', choices=['relu', 'tanh']))
-        >>> algo = TuneBOHB(
-                config_space, max_concurrent=4, metric='mean_loss', mode='min')
-        >>> bohb = HyperBandForBOHB(
-                time_attr='training_iteration',
-                metric='mean_loss',
-                mode='min',
-                max_t=100)
-        >>> run(MyTrainableClass, scheduler=bohb, search_alg=algo)
+
+    .. code-block:: python
+
+        import ConfigSpace as CS
+
+        config_space = CS.ConfigurationSpace()
+        config_space.add_hyperparameter(
+            CS.UniformFloatHyperparameter('width', lower=0, upper=20))
+        config_space.add_hyperparameter(
+            CS.UniformFloatHyperparameter('height', lower=-100, upper=100))
+        config_space.add_hyperparameter(
+            CS.CategoricalHyperparameter(
+                name='activation', choices=['relu', 'tanh']))
+
+        algo = TuneBOHB(
+            config_space, max_concurrent=4, metric='mean_loss', mode='min')
+        bohb = HyperBandForBOHB(
+            time_attr='training_iteration',
+            metric='mean_loss',
+            mode='min',
+            max_t=100)
+        run(MyTrainableClass, scheduler=bohb, search_alg=algo)
 
     """
 

python/ray/tune/suggest/dragonfly.py

@@ -18,7 +18,7 @@ logger = logging.getLogger(__name__)
 class DragonflySearch(SuggestionAlgorithm):
     """A wrapper around Dragonfly to provide trial suggestions.
 
-    Requires Dragonfly to be installed.
+    Requires Dragonfly to be installed via ``pip install dragonfly-opt``.
 
     Parameters:
         optimizer (dragonfly.opt.BlackboxOptimiser): Optimizer provided
@@ -40,33 +40,39 @@ class DragonflySearch(SuggestionAlgorithm):
             needing to re-compute the trial. Must be the same length as
             points_to_evaluate.
 
-    Example:
-        >>> from dragonfly.opt.gp_bandit import EuclideanGPBandit
-        >>> from dragonfly.exd.experiment_caller import EuclideanFunctionCaller
-        >>> from dragonfly import load_config
-        >>> domain_vars = [{
-                "name": "LiNO3_vol",
-                "type": "float",
-                "min": 0,
-                "max": 7
-            }, {
-                "name": "Li2SO4_vol",
-                "type": "float",
-                "min": 0,
-                "max": 7
-            }, {
-                "name": "NaClO4_vol",
-                "type": "float",
-                "min": 0,
-                "max": 7
-            }]
+    .. code-block:: python
 
-        >>> domain_config = load_config({"domain": domain_vars})
-        >>> func_caller = EuclideanFunctionCaller(None,
-                domain_config.domain.list_of_domains[0])
-        >>> optimizer = EuclideanGPBandit(func_caller, ask_tell_mode=True)
-        >>> algo = DragonflySearch(optimizer, max_concurrent=4,
-                metric="objective", mode="max")
+        from ray import tune
+        from dragonfly.opt.gp_bandit import EuclideanGPBandit
+        from dragonfly.exd.experiment_caller import EuclideanFunctionCaller
+        from dragonfly import load_config
+
+        domain_vars = [{
+            "name": "LiNO3_vol",
+            "type": "float",
+            "min": 0,
+            "max": 7
+        }, {
+            "name": "Li2SO4_vol",
+            "type": "float",
+            "min": 0,
+            "max": 7
+        }, {
+            "name": "NaClO4_vol",
+            "type": "float",
+            "min": 0,
+            "max": 7
+        }]
+
+        domain_config = load_config({"domain": domain_vars})
+        func_caller = EuclideanFunctionCaller(None,
+            domain_config.domain.list_of_domains[0])
+        optimizer = EuclideanGPBandit(func_caller, ask_tell_mode=True)
+
+        algo = DragonflySearch(optimizer, max_concurrent=4,
+            metric="objective", mode="max")
+
+        tune.run(my_func, algo=algo)
     """
 
     def __init__(self,

python/ray/tune/suggest/hyperopt.py

@@ -52,20 +52,22 @@ class HyperOptSearch(SuggestionAlgorithm):
         use_early_stopped_trials (bool): Whether to use early terminated
             trial results in the optimization process.
 
-    Example:
-        >>> space = {
-        >>>     'width': hp.uniform('width', 0, 20),
-        >>>     'height': hp.uniform('height', -100, 100),
-        >>>     'activation': hp.choice("activation", ["relu", "tanh"])
-        >>> }
-        >>> current_best_params = [{
-        >>>     'width': 10,
-        >>>     'height': 0,
-        >>>     'activation': 0, # The index of "relu"
-        >>> }]
-        >>> algo = HyperOptSearch(
-        >>>     space, max_concurrent=4, metric="mean_loss", mode="min",
-        >>>     points_to_evaluate=current_best_params)
+    .. code-block:: python
+
+        space = {
+            'width': hp.uniform('width', 0, 20),
+            'height': hp.uniform('height', -100, 100),
+            'activation': hp.choice("activation", ["relu", "tanh"])
+        }
+        current_best_params = [{
+            'width': 10,
+            'height': 0,
+            'activation': 0, # The index of "relu"
+        }]
+        algo = HyperOptSearch(
+            space, max_concurrent=4, metric="mean_loss", mode="min",
+            points_to_evaluate=current_best_params)
+
     """
 
     def __init__(self,

python/ray/tune/suggest/sigopt.py

@@ -30,27 +30,30 @@ class SigOptSearch(SuggestionAlgorithm):
             minimizing or maximizing the metric attribute.
 
     Example:
-        >>> space = [
-        >>>     {
-        >>>         'name': 'width',
-        >>>         'type': 'int',
-        >>>         'bounds': {
-        >>>             'min': 0,
-        >>>             'max': 20
-        >>>         },
-        >>>     },
-        >>>     {
-        >>>         'name': 'height',
-        >>>         'type': 'int',
-        >>>         'bounds': {
-        >>>             'min': -100,
-        >>>             'max': 100
-        >>>         },
-        >>>     },
-        >>> ]
-        >>> algo = SigOptSearch(
-        >>>     space, name="SigOpt Example Experiment",
-        >>>     max_concurrent=1, metric="mean_loss", mode="min")
+
+    .. code-block:: python
+
+        space = [
+            {
+                'name': 'width',
+                'type': 'int',
+                'bounds': {
+                    'min': 0,
+                    'max': 20
+                },
+            },
+            {
+                'name': 'height',
+                'type': 'int',
+                'bounds': {
+                    'min': -100,
+                    'max': 100
+                },
+            },
+        ]
+        algo = SigOptSearch(
+            space, name="SigOpt Example Experiment",
+            max_concurrent=1, metric="mean_loss", mode="min")
     """
 
     def __init__(self,

python/ray/tune/suggest/suggestion.py

@@ -20,12 +20,13 @@ class SuggestionAlgorithm(SearchAlgorithm):
     `suggest` will be passed a trial_id, which will be used in
     subsequent notifications.
 
-    Example:
-        >>> suggester = SuggestionAlgorithm()
-        >>> suggester.add_configurations({ ... })
-        >>> new_parameters = suggester.suggest()
-        >>> suggester.on_trial_complete(trial_id, result)
-        >>> better_parameters = suggester.suggest()
+    .. code-block:: python
+
+        suggester = SuggestionAlgorithm()
+        suggester.add_configurations({ ... })
+        new_parameters = suggester.suggest()
+        suggester.on_trial_complete(trial_id, result)
+        better_parameters = suggester.suggest()
     """
 
     def __init__(self, metric=None, mode="max", use_early_stopped_trials=True):