[DOC] modify intro

docs/Intro/Bridge.rst

@@ -10,7 +10,11 @@
 Bridge
 ======
 
-Bridging learning and reasoning parts to train the model is the fundamental idea of Abductive Learning. ABL-Package implements a set of bridge classes to achieve this.
+In this section, we will look at how to bridge learning and reasoning parts to train the model, which is the fundamental idea of Abductive Learning. ABL-Package implements a set of bridge classes to achieve this.
+
+.. code:: python
+
+    from abl.bridge import BaseBridge, SimpleBridge
 
 ``BaseBridge`` is an abstract class with the following initialization parameters:
 
@@ -40,7 +44,6 @@ Bridging learning and reasoning parts to train the model is the fundamental idea
 
 where ``train_data`` and ``test_data`` are both in the form of ``(X, gt_pseudo_label, Y)``. They will be used to construct ``ListData`` instances which are referred to as ``data_samples`` in the ``train`` and ``test`` methods respectively. More details can be found in `preparing datasets <Datasets.html>`_.
 
-
 ``SimpleBridge`` inherits from ``BaseBridge`` and provides a basic implementation. Besides the ``model`` and ``reasoner``, ``SimpleBridge`` has an extra initialization arguments, ``metric_list``, which will be used to evaluate model performance. Its training process involves several Abductive Learning loops and each loop consists of the following five steps:
 
   1. Predict class probabilities and indices for the given data samples.

docs/Intro/Datasets.rst

@@ -10,20 +10,27 @@
 Dataset & Data Structure
 ========================
 
+In this section, we will look at the datasets and data structures in ABL-Package.
+
+.. code:: python
+
+    import torch
+    from abl.structures import ListData
+
 Dataset
 -------
 
 ABL-Package assumes user data to be structured as a tuple, comprising the following three components:
 
 - ``X``: List[List[Any]]
-    A list of sublists representing the input data. We refer to each sublist in ``X`` as an instance and each instance may contain several elements.
+    A list of sublists representing the input data. We refer to each sublist in ``X`` as an sample and each sample may contain several instances.
 - ``gt_pseudo_label``: List[List[Any]], optional
-    A list of sublists with each sublist representing ground truth pseudo labels for each **element** within an instance of ``X``. 
+    A list of sublists with each sublist representing a ground truth pseudo label sample. Each sample consists of ground truth pseudo labels for each **instance** within a sample of ``X``. 
 - ``Y``: List[Any]
-    A list representing the ground truth reasoning result for each **instance** in ``X``.
+    A list representing the ground truth reasoning result for each **sample** in ``X``.
 
 .. warning::
-    Each sublist in ``gt_pseudo_label`` should have the same length as the sublist in ``X``. ``gt_pseudo_label`` is only used to evaluate the performance of the learning part but not to train the model. If the pseudo label of the elements in the datasets are unlabeled, ``gt_pseudo_label`` can be ``None``.
+    Each sublist in ``gt_pseudo_label`` should have the same length as the sublist in ``X``. ``gt_pseudo_label`` is only used to evaluate the performance of the learning part but not to train the model. If the pseudo label of the instances in the datasets are unlabeled, ``gt_pseudo_label`` can be ``None``.
 
 As an illustration, in the MNIST Addition example, the data used for training are organized as follows:
 
@@ -40,9 +47,6 @@ One of the most commonly used abstract data interface is ``ListData``. Besides o
 
 .. code-block:: python
 
-    import torch
-    from abl.structures import ListData
-
     # prepare data
     X = [list(torch.randn(3, 28, 28)), list(torch.randn(3, 28, 28))]
     gt_pseudo_label = [[1, 2, 3], [4, 5, 6]]

docs/Intro/Evaluation.rst

@@ -10,7 +10,11 @@
 Evaluation Metrics
 ==================
 
-ABL-Package seperates the evaluation process from model training and testing as an independent class, ``BaseMetric``. The training and testing processes are implemented in the ``BaseBridge`` class, so metrics are used by this class and its sub-classes. After building a ``bridge`` with a list of ``BaseMetric`` instances, these metrics will be used by the ``bridge.valid`` method to evaluate the model performance during training and testing. 
+In this section, we will look at how to build evaluation metrics. ABL-Package seperates the evaluation process from model training and testing as an independent class, ``BaseMetric``. The training and testing processes are implemented in the ``BaseBridge`` class, so metrics are used by this class and its sub-classes. After building a ``bridge`` with a list of ``BaseMetric`` instances, these metrics will be used by the ``bridge.valid`` method to evaluate the model performance during training and testing. 
+
+.. code:: python
+
+    from abl.evaluation import BaseMetric, SymbolMetric, ReasoningMetric
 
 To customize our own metrics, we need to inherit from ``BaseMetric`` and implement the ``process`` and ``compute_metrics`` methods. 
 

docs/Intro/Learning.rst

@@ -10,7 +10,13 @@
 Learning Part
 =============
 
-Learning part is constructed by first defining a base machine learning model and then wrap it into an instance of ``ABLModel`` class. 
+In this section, we will look at how to build the learning part. In ABL-Package, learning part is constructed by first defining a base machine learning model, and then wrap it into an instance of ``ABLModel`` class. 
+
+.. code:: python
+
+    import sklearn
+    import torchvision
+    from abl.learning import BasicNN, ABLModel
 
 For base model, ABL package allows it to be one of the following forms:  
 
@@ -18,15 +24,12 @@ For base model, ABL package allows it to be one of the following forms:
 
 2. A PyTorch-based neural network, provided it has defined the architecture and implemented the ``forward`` method. 
 
-However, base models are typically trained and make predictions on instance-level data, e.g. single images in the MNIST dataset, and therefore can not directly utilize sample-level data to train and predict, which is not suitable for most neural-symbolic tasks. ABL-Package provides the ``ABLModel`` to solve this problem. This class serves as a unified wrapper for all base models, which enables the learning part to train, test, and predict on sample-level data. The following two parts shows how to construct an ``ABLModel`` from a scikit-learn model and a PyTorch-based neural network, respectively.
+However, base models are typically trained to make predictions on instance-level data, and can not directly utilize sample-level data to train and predict, which is not suitable for most neural-symbolic tasks. ABL-Package provides the ``ABLModel`` to solve this problem. This class serves as a unified wrapper for all base models, which enables the learning part to train, test, and predict on sample-level data. The following two parts shows how to construct an ``ABLModel`` from a scikit-learn model and a PyTorch-based neural network, respectively.
 
 For a scikit-learn model, we can directly use the model to create an instance of ``ABLModel``. For example, we can customize our machine learning model by
 
 .. code:: python
 
-    import sklearn
-    from abl.learning import ABLModel
-
     base_model = sklearn.neighbors.KNeighborsClassifier(n_neighbors=3)
     model = ABLModel(base_model)
 
@@ -35,7 +38,6 @@ For a PyTorch-based neural network, we first need to encapsulate it within a ``B
 .. code:: python
 
     # Load a PyTorch-based neural network
-    import torchvision
     cls = torchvision.models.resnet18(pretrained=True)
 
     # loss_fn and optimizer are used for training

docs/Intro/Quick-Start.rst

@@ -56,7 +56,7 @@ To facilitate uniform processing, ABL-Package provides the ``BasicNN`` class to
    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
    base_model = BasicNN(cls, loss_fn, optimizer, device)
 
-Afterward, we wrap the scikit-learn style model, ``base_model``, into an instance of ``ABLModel``. This class serves as a unified wrapper for all base models,  facilitating the learning part to train, test, and predict on sample-level data - such as equations in the MNIST Addition task.
+However, Base model built above are trained to make predictions on instance-level data (e.g., a single image), which is not suitable enough for our task. Therefore, we then wrap the ``base_model`` into an instance of ``ABLModel``. This class serves as a unified wrapper for base models, facilitating the learning part to train, test, and predict on sample-level data, (e.g., images that comprise the equation).
 
 .. code:: python