[Tune][Doc] Restructure API reference

.gitignore

@@ -119,6 +119,8 @@ scripts/nodes.txt
 /doc/_build
 /doc/source/_static/thumbs
 /doc/source/tune/generated_guides/
+/doc/source/*/api/doc/
+/doc/source/cluster/running-applications/job-submission/doc/
 
 # User-specific stuff:
 .idea/**/workspace.xml

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

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/package-ref.rst
     ../rllib/package_ref/index.rst
     ../workflows/api/api.rst

doc/source/tune/api/execution.rst

@@ -0,0 +1,43 @@
+Tune Execution (Tuner)
+======================
+
+.. _tune-run-ref:
+
+Tuner
+-----
+
+.. currentmodule:: ray.tune
+
+.. autosummary::
+    :toctree: doc/
+
+    Tuner
+    Tuner.fit
+
+Tuner Configuration
+~~~~~~~~~~~~~~~~~~~
+
+.. autosummary::
+    :toctree: doc/
+
+    TuneConfig
+
+Restoring a Tuner
+~~~~~~~~~~~~~~~~~
+
+.. autosummary::
+    :toctree: doc/
+
+    Tuner.restore
+    Tuner.can_restore
+    Tuner.get_results
+
+
+tune.run_experiments
+--------------------
+
+.. autosummary::
+    :toctree: doc/
+
+    run_experiments
+    Experiment

doc/source/tune/api/integration.rst

@@ -0,0 +1,105 @@
+.. _tune-integration:
+
+External library integrations for Ray Tune (tune.integration)
+=============================================================
+
+.. currentmodule:: ray
+
+Comet (tune.integration.comet)
+-------------------------------------------
+
+:ref:`See here for an example. <tune-comet-ref>`
+
+.. autosummary::
+    :toctree: doc/
+
+    air.integrations.comet.CometLoggerCallback
+    :noindex:
+
+.. _tune-integration-keras:
+
+Keras (tune.integration.keras)
+------------------------------------------------------
+
+.. autosummary::
+    :toctree: doc/
+
+    tune.integration.keras.TuneReportCallback
+    tune.integration.keras.TuneReportCheckpointCallback
+
+
+.. _tune-integration-mlflow:
+
+MLflow (tune.integration.mlflow)
+--------------------------------
+
+:ref:`See here for an example. <tune-mlflow-ref>`
+
+.. autosummary::
+    :toctree: doc/
+
+    air.integrations.mlflow.MLflowLoggerCallback
+    :noindex:
+    air.integrations.mlflow.setup_mlflow
+
+
+.. _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-wandb:
+
+Weights and Biases (tune.integration.wandb)
+-------------------------------------------
+
+:ref:`See here for an example. <tune-wandb-ref>`
+
+.. autosummary::
+    :toctree: doc/
+
+    air.integrations.wandb.WandbLoggerCallback
+    :noindex:
+    air.integrations.wandb.setup_wandb
+
+
+.. _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

doc/source/tune/api_docs/logging.rst → doc/source/tune/api/logging.rst

@@ -31,40 +31,54 @@ relevant ones (like accuracy, loss, etc.).
 .. image:: ../images/ray-tune-viskit.png
 
 
-TBXLogger
----------
+.. currentmodule:: ray
 
-.. autoclass:: ray.tune.logger.TBXLoggerCallback
+Tune Built-in Loggers
+---------------------
 
-JsonLogger
-----------
+.. autosummary::
+    :toctree: doc/
 
-.. autoclass:: ray.tune.logger.JsonLoggerCallback
+    tune.logger.JsonLoggerCallback
+    tune.logger.CSVLoggerCallback
+    tune.logger.TBXLoggerCallback
 
-CSVLogger
----------
 
-.. autoclass:: ray.tune.logger.CSVLoggerCallback
-
-MLFlowLogger
-------------
+MLFlow Integration: MLFlowLoggerCallback
+----------------------------------------
 
 Tune also provides a logger for `MLflow <https://mlflow.org>`_.
 You can install MLflow via ``pip install mlflow``.
 You can see the :doc:`tutorial here </tune/examples/tune-mlflow>`.
 
-WandbLogger
------------
+.. autosummary::
+    :toctree: doc/
+
+    air.integrations.mlflow.MLflowLoggerCallback
+
+Wandb Integration: WandbLoggerCallback
+--------------------------------------
 
 Tune also provides a logger for `Weights & Biases <https://www.wandb.ai/>`_.
 You can install Wandb via ``pip install wandb``.
-You can see the :doc:`tutorial here </tune/examples/tune-wandb>`
+You can see the :doc:`tutorial here </tune/examples/tune-wandb>`.
 
+.. autosummary::
+    :toctree: doc/
+
+    air.integrations.wandb.WandbLoggerCallback
 
 .. _logger-interface:
 
-LoggerCallback
---------------
+LoggerCallback Interface
+------------------------
+
+.. autosummary::
+    :toctree: doc/
 
-.. autoclass:: ray.tune.logger.LoggerCallback
-    :members: log_trial_start, log_trial_restore, log_trial_save, log_trial_result, log_trial_end
+    tune.logger.LoggerCallback
+    tune.logger.LoggerCallback.log_trial_start
+    tune.logger.LoggerCallback.log_trial_restore
+    tune.logger.LoggerCallback.log_trial_save
+    tune.logger.LoggerCallback.log_trial_result
+    tune.logger.LoggerCallback.log_trial_end

doc/source/tune/api_docs/reporters.rst → doc/source/tune/api/reporters.rst

@@ -88,21 +88,26 @@ The default reporting style can also be overridden more broadly by extending the
     results = tuner.fit()
 
 
-CLIReporter
------------
+.. currentmodule:: ray.tune
 
-.. autoclass:: ray.tune.CLIReporter
-    :members: add_metric_column
+Reporter Interface (tune.ProgressReporter)
+------------------------------------------
 
-JupyterNotebookReporter
------------------------
+.. autosummary::
+    :toctree: doc/
+
+    ProgressReporter
+    ProgressReporter.report
+    ProgressReporter.should_report
 
-.. autoclass:: ray.tune.JupyterNotebookReporter
-    :members: add_metric_column
 
+Tune Built-in Reporters
+-----------------------
 
-ProgressReporter
-----------------
+.. autosummary::
+    :toctree: doc/
 
-.. autoclass:: ray.tune.ProgressReporter
-    :members:
+    CLIReporter
+    CLIReporter.add_metric_column
+    JupyterNotebookReporter
+    JupyterNotebookReporter.add_metric_column

doc/source/tune/api/result_grid.rst

@@ -0,0 +1,40 @@
+.. _tune-analysis-docs:
+
+.. _result-grid-docstring:
+
+ResultGrid (tune.ResultGrid)
+============================
+
+.. currentmodule:: ray
+
+.. autosummary::
+    :toctree: doc/
+
+    tune.ResultGrid
+    tune.ResultGrid.get_best_result
+    tune.ResultGrid.get_dataframe
+
+.. _result-docstring:
+
+Result (air.Result)
+-------------------
+
+.. autosummary::
+    :toctree: doc/
+
+    air.Result
+
+.. _exp-analysis-docstring:
+
+ExperimentAnalysis (tune.ExperimentAnalysis)
+--------------------------------------------
+
+.. note::
+
+    An experiment analysis is the output of the ``tune.run`` API.
+    It's now recommended to use ``Tuner.fit``, which outputs a ``ResultGrid`` object.
+
+.. autosummary::
+    :toctree: doc/
+
+    tune.ExperimentAnalysis