Update docs for get_started part (#3175)

* Add intro update

* Fix side bar

* Fix index

* Fix intro

docs/source/guide/explanation/additional_features/class_incremental_sampler.rst

@@ -0,0 +1,58 @@
+Class-Incremental Sampler
+===========================
+
+This sampler is a sampler that creates an effective batch.
+For default setting, the square root of (number of old data/number of new data) is used as the ratio of old data.
+
+.. tab-set::
+
+    .. tab-item:: API
+
+        .. code-block:: python
+
+            from otx.algo.samplers.class_incremental_sampler import ClassIncrementalSampler
+
+            dataset = OTXDataset(...)
+            class_incr_sampler = ClassIncrementalSampler(
+                dataset=dataset,
+                batch_size=32,
+                old_classes=["car", "truck"],
+                new_classes=["bus"],
+            )
+
+    .. tab-item:: CLI
+
+        .. code-block:: shell
+
+            (otx) ...$ otx train ... \
+                                 --data.config.train_subset.sampler.class_path otx.algo.samplers.class_incremental_sampler.ClassIncrementalSampler \
+                                 --data.config.train_subset.sampler.init_args.old_classes '[car,truck]' \
+                                 --data.config.train_subset.sampler.init_args.new_classes '[bus]'
+
+
+Balanced Sampler
+===========================
+
+This sampler is a sampler that creates an effective batch.
+It helps ensure balanced sampling by class based on the distribution of class labels during supervised learning.
+
+
+.. tab-set::
+
+    .. tab-item:: API
+
+        .. code-block:: python
+
+            from otx.algo.samplers.balanced_sampler import BalancedSampler
+
+            dataset = OTXDataset(...)
+            class_incr_sampler = BalancedSampler(
+                dataset=dataset,
+            )
+
+    .. tab-item:: CLI
+
+        .. code-block:: shell
+
+            (otx) ...$ otx train ... \
+                                 --data.config.train_subset.sampler.class_path otx.algo.samplers.balanced_sampler.BalancedSampler

docs/source/guide/explanation/additional_features/index.rst

@@ -13,3 +13,4 @@ Additional Features
    xai
    fast_data_loading
    tiling
+   class_incremental_sampler

docs/source/guide/get_started/api_tutorial.rst

@@ -1,10 +1,10 @@
-OpenVINO™ Training Extensions API Quick-Start
+:octicon:`code-square;1em` API Quick-Guide
 ==============================================
 
 Besides CLI functionality, The OpenVINO™ Training Extension provides APIs that help developers to integrate OpenVINO™ Training Extensions models into their projects.
 This tutorial intends to show how to create a dataset, model and use all of the CLI functionality through APIs.
 
-For demonstration purposes we will use the Object Detection SSD model with `WGISD <https://github.com/thsant/wgisd>`_ public dataset as we did for the :doc:`CLI tutorial <../tutorials/base/how_to_train/detection>`.
+For demonstration purposes we will use the Object Detection ATSS model with `WGISD <https://github.com/thsant/wgisd>`_ public dataset as we did for the :doc:`CLI tutorial <../tutorials/base/how_to_train/detection>`.
 
 .. note::
 
@@ -19,25 +19,25 @@ with `WGISD dataset <https://github.com/thsant/wgisd>`_.
 
 .. code-block:: shell
 
-  cd data
-  git clone https://github.com/thsant/wgisd.git
-  cd wgisd
-  git checkout 6910edc5ae3aae8c20062941b1641821f0c30127
+    cd data
+    git clone https://github.com/thsant/wgisd.git
+    cd wgisd
+    git checkout 6910edc5ae3aae8c20062941b1641821f0c30127
 
 2. We need to rename annotations to
 be distinguished by OpenVINO™ Training Extensions Datumaro manager:
 
 .. code-block:: shell
 
-    mv data images && mv coco_annotations annotations && mv annotations/train_bbox_instances.json instances_train.json  && mv annotations/test_bbox_instances.json instances_val.json
+    mv data images && mv coco_annotations annotations && mv annotations/train_bbox_instances.json instances_train.json && mv annotations/test_bbox_instances.json instances_val.json
 
 Now it is all set to use this dataset inside OpenVINO™ Training Extensions
 
 ************************************
 Quick Start with auto-configuration
 ************************************
 
-Once the dataset is ready, we can immediately start training with the model and data pipeline recommended by OTX through auto-configuration.
+Once the dataset is ready, we can immediately start training with the model and data pipeline recommended by OpenVINO™ Training Extension through auto-configuration.
 The following code snippet demonstrates how to use the auto-configuration feature:
 
 .. code-block:: python
@@ -50,7 +50,7 @@ The following code snippet demonstrates how to use the auto-configuration featur
 
 .. note::
 
-    If dataset supports multiple Task types, this will default to the Task type detected by OTX.
+    If dataset supports multiple Task types, this will default to the Task type detected by OpenVINO™ Training Extension.
     If you want to specify a specific Task type, you need to specify it like below:
 
     .. code-block:: python
@@ -65,35 +65,55 @@ The following code snippet demonstrates how to use the auto-configuration featur
 Check Available Model Recipes
 **********************************
 
-If you want to use other models offered by OTX besides the ones provided by Auto-Configuration, you can get a list of available models in OTX as shown below.
+If you want to use other models offered by OpenVINO™ Training Extension besides the ones provided by Auto-Configuration, you can get a list of available models in OpenVINO™ Training Extension as shown below.
 
-.. code-block:: python
+.. tab-set::
+
+    .. tab-item:: List of available model names
+
+        .. code-block:: python
+
+            from otx.engine.utils.api import list_models
+
+            model_lists = list_models(task="DETECTION")
+            print(model_lists)
+
+            '''
+            [
+                'yolox_tiny_tile',
+                'yolox_x',
+                'yolox_l_tile',
+                'yolox_x_tile', 'yolox_l',
+                'atss_r50_fpn',
+                'ssd_mobilenetv2',
+                'yolox_s',
+                'yolox_tiny',
+                'openvino_model',
+                'atss_mobilenetv2',
+                'yolox_s_tile',
+                'rtmdet_tiny',
+                'atss_mobilenetv2_tile',
+                'atss_resnext101',
+                'ssd_mobilenetv2_tile',
+            ]
+            '''
+
+    .. tab-item:: Print available configuration information
+
+        .. code-block:: python
+
+            from otx.engine.utils.api import list_models
 
-    from otx.engine.utils.api import list_models
-
-    model_lists = list_models(task="DETECTION")
-    print(model_lists)
-
-    '''
-    [
-        'yolox_tiny_tile',
-        'yolox_x',
-        'yolox_l_tile',
-        'yolox_x_tile', 'yolox_l',
-        'atss_r50_fpn',
-        'ssd_mobilenetv2',
-        'yolox_s',
-        'yolox_tiny',
-        'openvino_model',
-        'atss_mobilenetv2',
-        'yolox_s_tile',
-        'rtmdet_tiny',
-        'atss_mobilenetv2_tile',
-        'atss_resnext101',
-        'ssd_mobilenetv2_tile',
-    ]
-    '''
+            model_lists = list_models(task="DETECTION", print_table=True)
 
+            '''
+            ┏━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓            
+            ┃ Task      ┃ Model Name            ┃ Recipe Path                                                    ┃            
+            ┡━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩            
+            │ DETECTION │ yolox_tiny            │ src/otx/recipe/detection/yolox_tiny.yaml                       │            
+            │ ...       │                       │                                                                │
+            └───────────┴───────────────────────┴────────────────────────────────────────────────────────────────┘
+            '''
 
 .. note::
 
@@ -170,7 +190,7 @@ The current default setting is ``auto``.
 In addition, the ``Engine`` constructor can be associated with the Trainer's constructor arguments to control the Trainer's functionality.
 Refer `lightning.Trainer <https://lightning.ai/docs/pytorch/stable/common/trainer.html>`_.
 
-4. Using the OTX configuration we can configure the Engine.
+4. Using the OpenVINO™ Training Extension configuration we can configure the Engine.
 
 .. code-block:: python
 
@@ -190,7 +210,7 @@ Training
 
 Create an output model and start actual training:
 
-1. Below is an example using the ``atss_mobilenetv2`` model provided by OTX.
+1. Below is an example using the ``atss_mobilenetv2`` model provided by OpenVINO™ Training Extension.
 
 .. code-block:: python
 
@@ -212,7 +232,7 @@ Create an output model and start actual training:
 
 .. note::
 
-    This can use callbacks provided by OTX and several training techniques.
+    This can use callbacks provided by OpenVINO™ Training Extension and several training techniques.
     However, in this case, no arguments are specified for train.
 
 3. If you want to specify the model, you can do so as shown below:
@@ -435,7 +455,7 @@ The default value for ``export_precision`` is ``FP32``.
 
         .. code-block:: python
 
-            engine.export(precision="FP16")
+            engine.export(export_precision="FP16")
 
 
 ****

docs/source/guide/get_started/cli_commands.rst

@@ -1,13 +1,13 @@
-OpenVINO™ Training Extensions CLI Usage
+:octicon:`terminal;1em` CLI Guide
 ==========================================
 
 All possible OpenVINO™ Training Extensions CLI commands are presented below along with some general examples of how to run specific functionality. There are :doc:`dedicated tutorials <../tutorials/base/how_to_train/index>` in our documentation with life-practical examples on specific datasets for each task.
 
 .. note::
 
     To run CLI commands you need to prepare a dataset. Each task requires specific data formats. To know more about which formats are supported by each task, refer to :doc:`explanation section <../explanation/algorithms/index>` in the documentation.
-    Also, by default, the OTX CLI is written using jsonargparse, see jsonargparse or LightningCLI.
-    `Jsonargparse Documentation <https://jsonargparse.readthedocs.io/en/v4.27.4/#configuration-files>_`
+    Also, by default, the OpenVINO™ Training Extensions CLI is written using jsonargparse, see jsonargparse or LightningCLI.
+    Please refer `Jsonargparse Documentation <https://jsonargparse.readthedocs.io/en/v4.27.4/#configuration-files>`_
 
 *****
 Help
@@ -198,7 +198,7 @@ Users can also pre-generate a config file with an example like the one below.
 Find
 *****
 
-``otx find`` lists model templates and backbones available for the given task. Specify the task name with ``--task`` option. Use ``--pattern`` to find the model name from OTX.
+``otx find`` lists model templates and backbones available for the given task. Specify the task name with ``--task`` option. Use ``--pattern`` to find the model name from OpenVINO™ Training Extensions.
 
 .. code-block:: shell
 
@@ -304,29 +304,48 @@ The results will be saved in ``./otx-workspace/`` folder by default. The output
 ``otx train`` receives ``--config`` as a argument. ``config`` can be a path to the specific ``*.yaml`` file. Also, the path to data root should be passed to the CLI to start training.
 
 
+.. tab-set::
 
-Example of the command line to start training using Auto-Configuration:
+    .. tab-item:: Auto-Configuration
 
-.. code-block:: shell
+        Example of the command line to start training using Auto-Configuration:
 
-    (otx) ...$ otx train --data_root <dataset-root> --task <TASK>
+        .. code-block:: shell
 
-You can use the recipe configuration provided by OTX. The corresponding configuration file can be found via ``otx find``.
+            (otx) ...$ otx train --data_root <dataset-root> --task <TASK>
 
-.. code-block:: shell
+    .. tab-item:: With Configuration
+
+        You can use the recipe configuration provided by OpenVINO™ Training Extensions. The corresponding configuration file can be found via ``otx find``.
+
+        .. code-block:: shell
+
+            (otx) ...$ otx train --config <config-file-path> --data_root <dataset-root>
+
+    .. tab-item:: With Custom Model
+
+        You can also use a custom model and data module. The model and data module can be passed as a class path or a configuration file.
+
+        .. code-block:: shell
+
+            (otx) ...$ otx train --model <model-class-path-or-name> --task <task-type> --data_root <dataset-root>
+
+        For example, if you want to use the ``otx.algo.detection.atss.ATSS`` model class, you can train it as shown below.
+
+        .. code-block:: shell
 
-    (otx) ...$ otx train --config <config-file-path> --data_root <dataset-root>
+            (otx) ...$ otx train --model otx.algo.detection.atss.ATSS --model.variant mobilenetv2 --task DETECTION ...
 
 .. note::
-  You also can visualize the training using ``Tensorboard`` as these logs are located in ``<work_dir>/tensorboard``.
+    You also can visualize the training using ``Tensorboard`` as these logs are located in ``<work_dir>/tensorboard``.
 
 .. note::
-  ``--data.config.mem_cache_size`` provides in-memory caching for decoded images in main memory.
-  If the batch size is large, such as for classification tasks, or if your dataset contains high-resolution images,
-  image decoding can account for a non-negligible overhead in data pre-processing.
-  This option can be useful for maximizing GPU utilization and reducing model training time in those cases.
-  If your machine has enough main memory, we recommend increasing this value as much as possible.
-  For example, you can cache approximately 10,000 of ``500x375~500x439`` sized images with ``--data.config.mem_cache_size 8GB``.
+    ``--data.config.mem_cache_size`` provides in-memory caching for decoded images in main memory.
+    If the batch size is large, such as for classification tasks, or if your dataset contains high-resolution images,
+    image decoding can account for a non-negligible overhead in data pre-processing.
+    This option can be useful for maximizing GPU utilization and reducing model training time in those cases.
+    If your machine has enough main memory, we recommend increasing this value as much as possible.
+    For example, you can cache approximately 10,000 of ``500x375~500x439`` sized images with ``--data.config.mem_cache_size 8GB``.
 
 It is also possible to start training by omitting the template and just passing the paths to dataset roots, then the :doc:`auto-configuration <../explanation/additional_features/auto_configuration>` will be enabled. Based on the dataset, OpenVINO™ Training Extensions will choose the task type and template with the best accuracy/speed trade-off.
 
@@ -340,7 +359,7 @@ For example, that is how you can change the max epochs and the batch size for th
 .. note::
 
     ``train``, ``test`` works based on ``lightning.Tranier``. You can change the Trainer component with the arguments of train and test. You can find more arguments in this documentation.
-    `Trainer <https://lightning.ai/docs/pytorch/stable/common/trainer.html>_`
+    `Trainer <https://lightning.ai/docs/pytorch/stable/common/trainer.html>`_
 
 **********
 Exporting
@@ -352,15 +371,15 @@ The command below performs exporting to the ``{work_dir}/`` path.
 
 .. code-block:: shell
 
-    (otx) ...$ otx export ... --checkpoint <path/to/trained/weights.pth>
+    (otx) ...$ otx export ... --checkpoint <path/to/trained/weights.ckpt>
 
 The command results in ``exported_model.xml``, ``exported_model.bin``.
 
 To use the exported model as an input for ``otx explain``, please dump additional outputs with internal information, using ``--explain``:
 
 .. code-block:: shell
 
-    (otx) ...$ otx export ... --checkpoint <path/to/trained/weights.pth> --explain True
+    (otx) ...$ otx export ... --checkpoint <path/to/trained/weights.ckpt> --explain True
 
 
 .. note::
@@ -387,8 +406,8 @@ Command example for optimizing OpenVINO™ model (.xml) with OpenVINO™ PTQ:
 
 .. code-block:: shell
 
-    (otx) ...$ otx optimize ... --checkpoint <path/to/openvino.xml> \
-                                --data_root <path/to/val/root> \
+    (otx) ...$ otx optimize ... --checkpoint <path/to/exported_model.xml> \
+                                --data_root <path/to/val/root>
 
 
 Thus, to use PTQ pass the path to exported IR (.xml) model.
@@ -419,7 +438,7 @@ The command below will evaluate the trained model on the provided dataset:
 
 .. note::
 
-    It is possible to pass both PyTorch weights ``.pth`` or OpenVINO™ IR ``openvino.xml`` to ``--checkpoint`` option.
+    It is possible to pass both PyTorch weights ``.ckpt`` or OpenVINO™ IR ``exported_model.xml`` to ``--checkpoint`` option.
 
 
 .. note::
@@ -449,13 +468,13 @@ The command below will generate saliency maps (heatmaps with red colored areas o
 
 .. note::
 
-    It is possible to pass both PyTorch weights ``.pth`` or OpenVINO™ IR ``openvino.xml`` to ``--load-weights`` option.
+    It is possible to pass both PyTorch weights ``.ckpt`` or OpenVINO™ IR ``exported_model.xml`` to ``--load-weights`` option.
 
 By default, the model is exported to the OpenVINO™ IR format without extra feature information needed for the ``explain`` function. To use OpenVINO™ IR model in ``otx explain``, please first export it with ``--explain`` parameter:
 
 .. code-block:: shell
 
-    (otx) ...$ otx export ... --checkpoint <path/to/trained/weights.pth> \
+    (otx) ...$ otx export ... --checkpoint <path/to/trained/weights.ckpt> \
                               --explain True
     (otx) ...$ otx explain ... --checkpoint outputs/openvino/with_features \
 
@@ -477,7 +496,7 @@ If we run a typical Training example, will have a folder like the one below as o
         20240000_000001/              # Deliverables from OTX CLI Second-Trial
 
 
-OTX considers the folder with ``.latest`` to be the root of the entire Workspace.
+OpenVINO™ Training Extensions considers the folder with ``.latest`` to be the root of the entire Workspace.
 ``.latest`` soft-links to the most recently trained output folder.
 
 Case 1: If a user specifies an output ``work_dir`` (An already existing workspace)