[train][docs] fix doc search issues, examples gallery & filter

doc/source/_static/css/custom.css

@@ -464,7 +464,7 @@ footer {
   color: var(--pst-color-text-secondary);
 }
 
-/* override default colors used in the Sphnix theme */
+/* override default colors used in the Sphinx theme */
 :root {
   --tabs-color-label-active: #0475DE;
   --tabs-color-label-hover: #0475DE;
@@ -486,3 +486,8 @@ footer {
 :root {
   --blue: #0475DE;
 }
+
+/* Make the hover color of tag/gallery buttons differ from "active" */
+.tag.btn-outline-primary:hover {
+    background-color: rgba(20, 99, 208, 0.62) !important;
+}

doc/source/_static/js/tags.js

@@ -23,22 +23,26 @@ window.addEventListener('load', () => {
       .then(panelTagMap => {
 
           for (const panelId in panelTagMap) {
-              let element = document.getElementsByClassName(panelId)[0];
-
-              // For each panel, attach data tags to the 4-th parent of the panel,
-              // which is the "div" element that we can later toggle.
-              // Sphinx Panels is too inflexible to allow us to attach data tags
-              // directly to the container.
-              for (let i = 0; i < 4; i++) {
-                  if (element.parentNode) {
-                      element = element.parentElement;
-                      element.setAttribute('data-tags', panelTagMap[panelId]);
-                  }
-                  else {
-                      console.log(panelId + ' has no parent element,' +
-                          'please check if the panel has been tagged correctly.');
+              try { // panel might not be in _this_ gallery
+                  let element = document.getElementsByClassName(panelId)[0];
+
+                  // For each panel, attach data tags to the 4-th parent of the panel,
+                  // which is the "div" element that we can later toggle.
+                  // Sphinx Panels is too inflexible to allow us to attach data tags
+                  // directly to the container.
+                  for (let i = 0; i < 4; i++) {
+                      if (element.parentNode) {
+                          element = element.parentElement;
+                          element.setAttribute('data-tags', panelTagMap[panelId]);
+                      }
+                      else {
+                          console.log(panelId + ' has no parent element,' +
+                              'please check if the panel has been tagged correctly.');
+                      }
                   }
               }
+              // simply skip panels not in this gallery
+              catch(err) {}
           }
 
           const allButton = document.getElementById('allButton')

doc/source/_toc.yml

@@ -74,15 +74,40 @@ parts:
         title: Ray Train
         sections:
           - file: train/getting-started
+            title: "Getting Started"
           - file: train/key-concepts
+            title: "Key Concepts"
           - file: train/user-guides
+            title: "User Guides"
             sections:
               - file: train/config_guide
+                title: "Configuring Ray Train"
               - file: train/dl_guide
+                title: "Deep Learning Guide"
               - file: train/gbdt
+                title: "XGBoost/LightGBM guide"
               - file: train/architecture
-          - file: train/faq
+                title: "Ray Train Architecture"
           - file: train/examples
+            title: "Examples"
+            sections:
+              - file: train/examples/pytorch/torch_fashion_mnist_example
+                title: "PyTorch Fashion MNIST Example"
+              - file: train/examples/transformers/transformers_example
+                title: "HF Transformers Example"
+              - file: train/examples/tf/tensorflow_mnist_example
+                title: "TensorFlow MNIST Example"
+              - file: train/examples/horovod/horovod_example
+                title: "Horovod Example"
+              - file: train/examples/mlflow_fashion_mnist_example
+                title: "MLflow Callback Example"
+              - file: train/examples/tf/tune_tensorflow_mnist_example
+                title: "Tune & TensorFlow Example"
+              - file: train/examples/pytorch/tune_cifar_torch_pbt_example
+                title: "Tune & PyTorch Example"
+              - file: train/examples/pytorch/torch_data_prefetch_benchmark/benchmark_example
+                title: "Torch Data Prefetching Benchmark"
+          - file: train/faq
           - file: train/api
 
       - file: tune/index

doc/source/conf.py

@@ -354,10 +354,19 @@
     "xgboostExample": "Classification,XGBoost,Training,Preprocessing,Prediction",
     "timeSeriesAutoML": "Regression,Sklearn,Tuning",
     "AIRExamples": "Regression,Classification,Training,Tuning,Prediction,"
-    "Preprocessing,Serving,PyTorch,TensorFlow,XGBoost,LightGBM,Sklearn"
+    "Preprocessing,Serving,PyTorch,TensorFlow,XGBoost,LightGBM,Sklearn",
+    # Tags for Ray Train examples gallery
+    "trainTorchFashionMnist": "PyTorch,Training",
+    "trainTransformers": "PyTorch,Training,HuggingFace",
+    "trainTensorflowMnist": "TensorFlow,Training",
+    "trainHorovod": "Horovod, PyTorch,Training",
+    "trainMlflow": "MLflow,Training",
+    "trainTuneTensorflow": "TensorFlow,Training,Tuning",
+    "trainTunePyTorch": "PyTorch,Training,Tuning",
+    "trainBenchmark": "PyTorch,Training"
     # TODO add and integrate tags for other libraries.
     # Tune has a proper example library
-    # Train, Serve, RLlib and AIR could use one.
+    # Serve, RLlib and AIR could use one.
 }
 
 # Create file with tag mappings for tags.js to use.

doc/source/train/api.rst

@@ -2,6 +2,7 @@
 
 Ray Train API
 =============
+
 This page covers framework specific integrations with Ray Train and Ray Train Developer APIs.
 
 For core Ray AIR APIs, take a look at the :ref:`AIR Trainer package reference <air-trainer-ref>`.
@@ -14,12 +15,17 @@ Trainer and Predictor Integrations
 XGBoost
 ~~~~~~~
 
+``XGBoostTrainer``
+******************
+
 .. autoclass:: ray.train.xgboost.XGBoostTrainer
     :members:
     :show-inheritance:
 
     .. automethod:: __init__
 
+``XGBoostPredictor``
+********************
 
 .. automodule:: ray.train.xgboost
     :members:
@@ -29,12 +35,18 @@ XGBoost
 LightGBM
 ~~~~~~~~
 
+``LightGBMTrainer``
+*******************
+
 .. autoclass:: ray.train.lightgbm.LightGBMTrainer
     :members:
     :show-inheritance:
 
     .. automethod:: __init__
 
+``LightGBMPredictor``
+*********************
+
 
 .. automodule:: ray.train.lightgbm
     :members:
@@ -44,12 +56,17 @@ LightGBM
 TensorFlow
 ~~~~~~~~~~
 
+``TensorflowTrainer``
+*********************
+
 .. autoclass:: ray.train.tensorflow.TensorflowTrainer
     :members:
     :show-inheritance:
 
     .. automethod:: __init__
 
+``TensorflowPredictor`` and ``TensorflowCheckpoint``
+****************************************************
 
 .. automodule:: ray.train.tensorflow
     :members:
@@ -59,13 +76,19 @@ TensorFlow
 PyTorch
 ~~~~~~~
 
+``TorchTrainer``
+****************
+
 .. autoclass:: ray.train.torch.TorchTrainer
     :members:
     :show-inheritance:
 
     .. automethod:: __init__
 
 
+``TorchPredictor``
+******************
+
 .. automodule:: ray.train.torch
     :members:
     :exclude-members: TorchTrainer
@@ -74,12 +97,17 @@ PyTorch
 Horovod
 ~~~~~~~
 
+``HorovodTrainer``
+******************
+
 .. autoclass:: ray.train.horovod.HorovodTrainer
     :members:
     :show-inheritance:
 
     .. automethod:: __init__
 
+``HorovodConfig``
+*****************
 
 .. automodule:: ray.train.horovod
     :members:
@@ -89,12 +117,17 @@ Horovod
 HuggingFace
 ~~~~~~~~~~~
 
+``HuggingFaceTrainer``
+**********************
+
 .. autoclass:: ray.train.huggingface.HuggingFaceTrainer
     :members:
     :show-inheritance:
 
     .. automethod:: __init__
 
+``HuggingFacePredictor`` and ``HuggingFaceCheckpoint``
+******************************************************
 
 .. automodule:: ray.train.huggingface
     :members:
@@ -104,12 +137,17 @@ HuggingFace
 Scikit-Learn
 ~~~~~~~~~~~~
 
+``SklearnTrainer``
+******************
+
 .. autoclass:: ray.train.sklearn.SklearnTrainer
     :members:
     :show-inheritance:
 
     .. automethod:: __init__
 
+``SklearnPredictor`` and ``SklearnCheckpoint``
+**********************************************
 
 .. automodule:: ray.train.sklearn
     :members:
@@ -119,6 +157,9 @@ Scikit-Learn
 Mosaic
 ~~~~~~
 
+``MosaicTrainer``
+*****************
+
 .. autoclass:: ray.train.mosaic.MosaicTrainer
     :members:
     :show-inheritance:
@@ -132,16 +173,32 @@ Mosaic
     :show-inheritance:
 
 
-Reinforcement Learning (RLlib)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Reinforcement Learning with RLlib
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``RLTrainer``
+*************
+
+.. autoclass:: ray.train.rl.RLTrainer
+    :members:
+    :show-inheritance:
+
+    .. automethod:: __init__
+
+``RLPredictor`` and ``RLCheckpoint``
+************************************
 
 .. automodule:: ray.train.rl
     :members:
+    :exclude-members: RLTrainer
     :show-inheritance:
 
 
 Base Classes (Developer APIs)
 -----------------------------
+
+.. _train-base-trainer:
+
 .. autoclass:: ray.train.trainer.BaseTrainer
     :members:
     :noindex:
@@ -165,8 +222,12 @@ Base Classes (Developer APIs)
     .. automethod:: __init__
         :noindex:
 
+.. _train-backend:
+
 .. autoclass:: ray.train.backend.Backend
     :members:
 
+.. _train-backend-config:
+
 .. autoclass:: ray.train.backend.BackendConfig
     :members: