[Tune][Doc] Restructure API reference (ray-project#32311)

Signed-off-by: Edward Oakes <[email protected]>
edoakes · Mar 22, 2023 · 9627e8d · 9627e8d
1 parent 895e52e
commit 9627e8d
Show file tree

Hide file tree

Showing 37 changed files with 1,983 additions and 1,745 deletions.
diff --git a/.gitignore b/.gitignore
@@ -119,6 +119,7 @@ scripts/nodes.txt
 /doc/_build
 /doc/source/_static/thumbs
 /doc/source/tune/generated_guides/
+/doc/source/**/doc/
 
 # User-specific stuff:
 .idea/**/workspace.xml

diff --git a/doc/source/_toc.yml b/doc/source/_toc.yml
@@ -282,7 +282,7 @@ parts:
               - file: tune/examples/exercises
                 title: "Exercises"
           - file: tune/faq
-          - file: tune/api_docs/overview.rst
+          - file: tune/api/api.rst
 
       - file: serve/index
         title: Ray Serve

diff --git a/doc/source/ray-air/package-ref.rst b/doc/source/ray-air/package-ref.rst
@@ -159,6 +159,7 @@ Training Session
 
 .. automodule:: ray.air.session
     :members:
+    :noindex:
 
 Trainer Configs
 ###############
@@ -364,26 +365,8 @@ Reinforcement Learning (RLlib)
 
 .. _air-builtin-callbacks:
 
-Monitoring Integrations
+Integrations
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Comet
-#####
-
-.. autoclass:: ray.air.integrations.comet.CometLoggerCallback
-
-Keras
-#####
-
-.. autoclass:: ray.air.integrations.keras.Callback
-    :members:
-
-MLflow
-######
-
-.. autoclass:: ray.air.integrations.mlflow.MLflowLoggerCallback
-
-Weights and Biases
-##################
-
-.. autoclass:: ray.air.integrations.wandb.WandbLoggerCallback
+See :doc:`this API reference </tune/api/integration>` for AIR integrations with other libraries
+such as Weights and Biases, MLFlow, Keras, and more.
diff --git a/doc/source/ray-references/api.rst b/doc/source/ray-references/api.rst
@@ -8,7 +8,7 @@ API References
     ../ray-air/package-ref.rst
     ../data/api/api.rst
     ../train/api.rst
-    ../tune/api_docs/overview.rst
+    ../tune/api/api.rst
     ../serve/api/index.rst
     ../rllib/package_ref/index.rst
     ../workflows/api/api.rst

diff --git a/doc/source/tune/api_docs/overview.rst → doc/source/tune/api/api.rst b/doc/source/tune/api_docs/overview.rst → doc/source/tune/api/api.rst
@@ -14,15 +14,16 @@ on `Github`_.
     :maxdepth: 2
 
     execution.rst
+    result_grid.rst
     trainable.rst
     search_space.rst
     suggestion.rst
     schedulers.rst
     stoppers.rst
-    result_grid.rst
     reporters.rst
     syncing.rst
     logging.rst
+    callbacks.rst
     env.rst
     sklearn.rst
     integration.rst

diff --git a/doc/source/tune/api/callbacks.rst b/doc/source/tune/api/callbacks.rst
@@ -0,0 +1,55 @@
+.. _tune-callbacks-docs:
+
+Tune Callbacks (tune.Callback)
+==============================
+
+See :doc:`this user guide </tune/tutorials/tune-metrics>` for more details.
+
+.. seealso::
+
+    :doc:`Tune's built-in loggers </tune/api/logging>` use the ``Callback`` interface.
+
+
+Callback Interface
+------------------
+
+Callback Initialization and Setup
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. currentmodule:: ray.tune
+.. autosummary::
+    :toctree: doc/
+
+    Callback
+    Callback.setup
+
+
+Callback Hooks
+~~~~~~~~~~~~~~
+
+.. autosummary::
+    :toctree: doc/
+
+    Callback.on_checkpoint
+    Callback.on_experiment_end
+    Callback.on_step_begin
+    Callback.on_step_end
+    Callback.on_trial_complete
+    Callback.on_trial_error
+    Callback.on_trial_restore
+    Callback.on_trial_result
+    Callback.on_trial_save
+    Callback.on_trial_start
+
+
+Stateful Callbacks
+~~~~~~~~~~~~~~~~~~
+
+The following methods must be overriden for stateful callbacks to be saved/restored
+properly by Tune.
+
+.. autosummary::
+    :toctree: doc/
+
+    Callback.get_state
+    Callback.set_state
diff --git a/doc/source/tune/api_docs/cli.rst → doc/source/tune/api/cli.rst b/doc/source/tune/api_docs/cli.rst → doc/source/tune/api/cli.rst
diff --git a/doc/source/tune/api_docs/client.rst → doc/source/tune/api/client.rst b/doc/source/tune/api_docs/client.rst → doc/source/tune/api/client.rst
diff --git a/doc/source/tune/api_docs/env.rst → doc/source/tune/api/env.rst b/doc/source/tune/api_docs/env.rst → doc/source/tune/api/env.rst
diff --git a/doc/source/tune/api/execution.rst b/doc/source/tune/api/execution.rst
@@ -0,0 +1,43 @@
+Tune Execution (tune.Tuner)
+===========================
+
+.. _tune-run-ref:
+
+Tuner
+-----
+
+.. currentmodule:: ray.tune
+
+.. autosummary::
+    :toctree: doc/
+
+    Tuner
+    Tuner.fit
+    Tuner.get_results
+
+Tuner Configuration
+~~~~~~~~~~~~~~~~~~~
+
+.. autosummary::
+    :toctree: doc/
+
+    TuneConfig
+
+Restoring a Tuner
+~~~~~~~~~~~~~~~~~
+
+.. autosummary::
+    :toctree: doc/
+
+    Tuner.restore
+    Tuner.can_restore
+
+
+tune.run_experiments
+--------------------
+
+.. autosummary::
+    :toctree: doc/
+
+    run_experiments
+    Experiment
diff --git a/doc/source/tune/api/integration.rst b/doc/source/tune/api/integration.rst
@@ -0,0 +1,115 @@
+.. _tune-integration:
+
+External library integrations for Ray Tune
+===========================================
+
+.. TODO: Clean this up. Both tune.integration and air.integrations are
+..   captured here. Most of the `tune.integration` can be deprecated soon.
+..   XGBoost/LightGBM callbacks are no longer recommended - use their trainers instead
+..   which will automatically report+checkpoint.
+..   After PTL trainer is introduced, we can also deprecate that callback.
+
+.. currentmodule:: ray
+
+.. _tune-monitoring-integrations:
+
+Tune Experiment Monitoring Integrations
+----------------------------------------
+
+Comet (air.integrations.comet)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:ref:`See here for an example. <tune-comet-ref>`
+
+.. autosummary::
+    :toctree: doc/
+
+    ~air.integrations.comet.CometLoggerCallback
+
+
+.. _tune-integration-mlflow:
+
+MLflow (air.integrations.mlflow)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:ref:`See here for an example. <tune-mlflow-ref>`
+
+.. autosummary::
+    :toctree: doc/
+
+    ~air.integrations.mlflow.MLflowLoggerCallback
+    ~air.integrations.mlflow.setup_mlflow
+
+.. _tune-integration-wandb:
+
+Weights and Biases (air.integrations.wandb)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:ref:`See here for an example. <tune-wandb-ref>`
+
+.. autosummary::
+    :toctree: doc/
+
+    ~air.integrations.wandb.WandbLoggerCallback
+    ~air.integrations.wandb.setup_wandb
+
+
+Integrations with ML Libraries
+--------------------------------
+
+.. _tune-integration-keras:
+
+Keras (air.integrations.keras)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autosummary::
+    :toctree: doc/
+
+    ~air.integrations.keras.ReportCheckpointCallback
+
+
+.. _tune-integration-mxnet:
+
+MXNet (tune.integration.mxnet)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autosummary::
+    :toctree: doc/
+
+    ~tune.integration.mxnet.TuneReportCallback
+    ~tune.integration.mxnet.TuneCheckpointCallback
+
+
+.. _tune-integration-pytorch-lightning:
+
+PyTorch Lightning (tune.integration.pytorch_lightning)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autosummary::
+    :toctree: doc/
+
+    ~tune.integration.pytorch_lightning.TuneReportCallback
+    ~tune.integration.pytorch_lightning.TuneReportCheckpointCallback
+
+.. _tune-integration-xgboost:
+
+XGBoost (tune.integration.xgboost)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autosummary::
+    :toctree: doc/
+
+    ~tune.integration.xgboost.TuneReportCallback
+    ~tune.integration.xgboost.TuneReportCheckpointCallback
+
+
+.. _tune-integration-lightgbm:
+
+LightGBM (tune.integration.lightgbm)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autosummary::
+    :toctree: doc/
+
+    ~tune.integration.lightgbm.TuneReportCallback
+    ~tune.integration.lightgbm.TuneReportCheckpointCallback
diff --git a/doc/source/tune/api_docs/internals.rst → doc/source/tune/api/internals.rst b/doc/source/tune/api_docs/internals.rst → doc/source/tune/api/internals.rst
@@ -3,6 +3,13 @@ Tune Internals
 
 .. _raytrialexecutor-docstring:
 
+TunerInternal
+---------------
+
+.. autoclass:: ray.tune.impl.tuner_internal.TunerInternal
+    :members:
+
+
 RayTrialExecutor
 ----------------
 
@@ -15,30 +22,22 @@ TrialRunner
 -----------
 
 .. autoclass:: ray.tune.execution.trial_runner.TrialRunner
+    :members:
 
 .. _trial-docstring:
 
 Trial
 -----
 
 .. autoclass:: ray.tune.experiment.trial.Trial
+    :members:
 
-.. _tune-callbacks-docs:
-
-Callbacks
----------
-
-.. autoclass:: ray.tune.callback.Callback
-   :members:
-
-
-.. _resources-docstring:
-
-PlacementGroupFactory
----------------------
+FunctionTrainable
+-----------------
 
-.. autoclass:: ray.tune.execution.placement_groups.PlacementGroupFactory
+.. autoclass:: ray.tune.trainable.function_trainable.FunctionTrainable
 
+.. autofunction:: ray.tune.trainable.function_trainable.wrap_function
 
 
 Registry