address comments

Signed-off-by: xwjiang2010 <xwjiang2010@gmail.com>

doc/source/ray-air/doc_code/tuner.py

@@ -25,17 +25,13 @@ def my_trainer(config):
 
 # __xgboost_start__
 
-from ray.data import from_pandas
-from sklearn.datasets import load_breast_cancer
-
 
 # Function that returns the training dataset
+import ray
+
+
 def get_dataset():
-    data_raw = load_breast_cancer(as_frame=True)
-    dataset_df = data_raw["data"]
-    dataset_df["target"] = data_raw["target"]
-    dataset = from_pandas(dataset_df)
-    return dataset
+    return ray.data.read_csv("s3://anonymous@air-example-data/breast_cancer.csv")
 
 
 from ray.train.xgboost import XGBoostTrainer
@@ -169,3 +165,37 @@ def get_dataset():
 
     print("The trial finished successfully with the metrics:", result.metrics)
 # __result_grid_inspection_end__
+
+# __run_config_start__
+from ray import air, tune
+from ray.air.config import RunConfig
+from ray.tune import Callback
+
+
+class MyCallback(Callback):  # Tuner expose callbacks for customer logics.
+    def on_trial_result(self, iteration, trials, trial, result, **info):
+        print(f"Got result: {result['metric']}")
+
+
+run_config = RunConfig(
+    name="MyExperiment",
+    callbacks=[MyCallback()],
+    sync_config=tune.SyncConfig(upload_dir="s3://..."),
+    checkpoint_config=air.CheckpointConfig(checkpoint_frequency=2),
+)
+
+# __run_config_end__
+
+# __tune_config_start__
+from ray.tune import TuneConfig
+from ray.tune.search.bayesopt import BayesOptSearch
+
+algo = BayesOptSearch(random_search_steps=4)
+
+tune_config = TuneConfig(
+    metric="score",
+    mode="min",
+    search_alg=algo,
+)
+
+# __tune_config_end__

doc/source/ray-air/tuner.rst

@@ -2,7 +2,7 @@
 
 Hyperparameter Tuning
 =====================
-The Ray AIR Tuner API is the recommended way to launch hyperparameter tuning jobs with Ray Tune.
+The Ray AIR Tuner API is the recommended way to launch hyperparameter tuning jobs in Ray AIR.
 
 Suppose that you already have a Ray AIR trainer at hand.
 You have fitted it and obtained a model and training results.
@@ -21,7 +21,9 @@ In this guide, we will show you how to do this.
 Basic usage
 -----------
 
-Assuming you already have your own Trainer, this is how the Ray Tune API works in a nutshell:
+Suppose that you already have your Ray AIR Trainer at hand.
+You have fitted it and obtained a model and training results.
+Below, we demonstrate how you can plug in your existing Trainer into a Tuner.
 
 .. literalinclude:: doc_code/tuner.py
     :language: python
@@ -32,17 +34,13 @@ Assuming you already have your own Trainer, this is how the Ray Tune API works i
 Defining the search space
 -------------------------
 
-The Tuner API takes in a `param_space` argument where you can define the search space that Ray Tune will
-use to try out hyperparameter configurations.
+The Tuner API takes in a `param_space` argument where you can define the search space
+from which hyperparameter configurations will be sampled.
 
 Generally, you can search over most arguments and configurations provided by Ray AIR (and your own options).
 This includes Ray Datasets, Preprocessors, the distributed training configuration (ScalingConfig)
 and general hyperparameters.
 
-The main exclusion here are all arguments of the :class:`ray.air.config.RunConfig`, which are inherently un-tunable.
-Another exclusion is the :class:`ray.tune.tune_config.TuneConfig`, which defines the tuning behavior itself - the settings
-apply to all trials and thus can't be tuned.
-
 Examples for common parameters (depending on the Trainer and model) you can tune are:
 
 - The training batch size
@@ -66,9 +64,10 @@ The following shows some example code on how to specify the ``param_space``.
         :end-before: __torch_end__
 
 
-As you can see in the above example, the Tuner API allows you to specify a search space over most parameters:
+As you can see in the above example, the Tuner API allows you to specify a search space over most parameters.
+The parameters will be passed to the Trainer.
 
-- Parameters will be passed to the Trainer
+A couple gotchas about the behavior of merging parameters with Trainer:
 - Dictionaries will be merged
 - Scaling configs will be merged
 - Duplicate items (which are both defined in the Trainer and Tuner) will be overwritten by the ones defined in the Tuner
@@ -87,14 +86,23 @@ The Tuner API allows you to even tune the train/validation datasets:
     :start-after: __tune_dataset_start__
     :end-before: __tune_dataset_end__
 
-In general, all the arguments accepted by your :ref:`Trainer <air-trainer-ref>` can be tuned
-(except for the :class:`ray.air.config.RunConfig`).
+In general, all the arguments accepted by your :ref:`Trainer <air-trainer-ref>` can be tuned.
+The main exclusion here are all arguments of the :class:`ray.air.config.RunConfig`, which are inherently un-tunable.
+Another exclusion is the :class:`ray.tune.tune_config.TuneConfig`, which defines the tuning behavior itself - the settings
+apply to all trials and thus can't be tuned.
 
 
 Specify TuneConfig
 ------------------
 This config contains tuning specific settings, including the tuning algorithm to use, the metric and mode to rank results etc.
 
+The following we showcase some common configuration of :class:`ray.tune.tune_config.TuneConfig`.
+
+.. literalinclude:: doc_code/tuner.py
+    :language: python
+    :start-after: __tune_config_start__
+    :end-before: __tune_config_end__
+
 See the :class:`Tuner <ray.tune.tuner.Tuner>` and the :class:`TuneConfig API reference <ray.tune.tune_config.TuneConfig>` for more details.
 
 
@@ -104,6 +112,13 @@ This config contains framework's runtime configurations that are more generic th
 This may include failure/retry configurations, verbosity levels, the name of the experiment, its logging directory,
 checkpoint configuration as well as its syncing configuration.
 
+The following we showcase some common configuration of :class:`ray.air.config.RunConfig`.
+
+.. literalinclude:: doc_code/tuner.py
+    :language: python
+    :start-after: __run_config_start__
+    :end-before: __run_config_end__
+
 See the :class:`RunConfig API reference <ray.air.config.RunConfig>` for more details.
 
 Putting everything together