Merge pull request #117 from FengZiYjun/fix-doc

[doc] Improve Documentation

Author: xpqiu

docs/source/conf.py

@@ -16,18 +16,16 @@
 import sys
 sys.path.insert(0, os.path.abspath('../../'))
 
-import sphinx_rtd_theme
-
 # -- Project information -----------------------------------------------------
 
 project = 'fastNLP'
 copyright = '2018, xpqiu'
 author = 'xpqiu'
 
 # The short X.Y version
-version = ''
+version = '0.2'
 # The full version, including alpha/beta/rc tags
-release = '1.0'
+release = '0.2'
 
 
 # -- General configuration ---------------------------------------------------

docs/source/figures/text_classification.png

@@ -5,21 +5,19 @@
 class Batch(object):
     """Batch is an iterable object which iterates over mini-batches.
 
-    ::
-        for batch_x, batch_y in Batch(data_set, batch_size=16, sampler=SequentialSampler()):
+        Example::
 
+            for batch_x, batch_y in Batch(data_set, batch_size=16, sampler=SequentialSampler()):
+                # ...
+
+    :param dataset: a DataSet object
+    :param batch_size: int, the size of the batch
+    :param sampler: a Sampler object
+    :param as_numpy: bool. If True, return Numpy array. Otherwise, return torch tensors.
 
     """
 
     def __init__(self, dataset, batch_size, sampler, as_numpy=False):
-        """
-
-        :param dataset: a DataSet object
-        :param batch_size: int, the size of the batch
-        :param sampler: a Sampler object
-        :param as_numpy: bool. If True, return Numpy array. Otherwise, return torch tensors.
-
-        """
         self.dataset = dataset
         self.batch_size = batch_size
         self.sampler = sampler

fastNLP/core/batch.py

@@ -118,7 +118,7 @@ def __getstate__(self):
     def __len__(self):
         """Fetch the length of the dataset.
 
-        :return int length:
+        :return length:
         """
         if len(self.field_arrays) == 0:
             return 0
@@ -170,7 +170,7 @@ def add_field(self, name, fields, padding_val=0, is_input=False, is_target=False
     def delete_field(self, name):
         """Delete a field based on the field name.
 
-        :param str name: the name of the field to be deleted.
+        :param name: the name of the field to be deleted.
         """
         self.field_arrays.pop(name)
 
@@ -182,14 +182,14 @@ def get_field(self, field_name):
     def get_all_fields(self):
         """Return all the fields with their names.
 
-        :return dict field_arrays: the internal data structure of DataSet.
+        :return field_arrays: the internal data structure of DataSet.
         """
         return self.field_arrays
 
     def get_length(self):
         """Fetch the length of the dataset.
 
-        :return int length:
+        :return length:
         """
         return len(self)
 
@@ -232,14 +232,14 @@ def set_input(self, *field_name, flag=True):
     def get_input_name(self):
         """Get all field names with `is_input` as True.
 
-        :return list field_names: a list of str
+        :return field_names: a list of str
         """
         return [name for name, field in self.field_arrays.items() if field.is_input]
 
     def get_target_name(self):
         """Get all field names with `is_target` as True.
 
-        :return list field_names: a list of str
+        :return field_names: a list of str
         """
         return [name for name, field in self.field_arrays.items() if field.is_target]
 
@@ -294,8 +294,9 @@ def split(self, dev_ratio):
         """Split the dataset into training and development(validation) set.
 
         :param float dev_ratio: the ratio of test set in all data.
-        :return DataSet train_set: the training set
-                DataSet dev_set: the development set
+        :return (train_set, dev_set):
+                train_set: the training set
+                dev_set: the development set
         """
         assert isinstance(dev_ratio, float)
         assert 0 < dev_ratio < 1
@@ -326,7 +327,7 @@ def read_csv(cls, csv_path, headers=None, sep=",", dropna=True):
         :param List[str] or Tuple[str] headers: headers of the CSV file
         :param str sep: delimiter in CSV file. Default: ","
         :param bool dropna: If True, drop rows that have less entries than headers.
-        :return DataSet dataset:
+        :return dataset: the read data set
 
         """
         with open(csv_path, "r") as f:
@@ -370,7 +371,7 @@ def load(path):
         """Load a DataSet object from pickle.
 
         :param str path: the path to the pickle
-        :return DataSet data_set:
+        :return data_set:
         """
         with open(path, 'rb') as f:
             return pickle.load(f)

fastNLP/core/dataset.py

@@ -2,20 +2,18 @@
 
 
 class FieldArray(object):
-    """FieldArray is the collection of Instances of the same Field.
-    It is the basic element of DataSet class.
+    """``FieldArray`` is the collection of ``Instance``s of the same field.
+    It is the basic element of ``DataSet`` class.
+
+    :param str name: the name of the FieldArray
+    :param list content: a list of int, float, str or np.ndarray, or a list of list of one, or a np.ndarray.
+    :param int padding_val: the integer for padding. Default: 0.
+    :param bool is_target: If True, this FieldArray is used to compute loss.
+    :param bool is_input: If True, this FieldArray is used to the model input.
 
     """
 
     def __init__(self, name, content, padding_val=0, is_target=None, is_input=None):
-        """
-
-        :param str name: the name of the FieldArray
-        :param list content: a list of int, float, str or np.ndarray, or a list of list of one, or a np.ndarray.
-        :param int padding_val: the integer for padding. Default: 0.
-        :param bool is_target: If True, this FieldArray is used to compute loss.
-        :param bool is_input: If True, this FieldArray is used to the model input.
-        """
         self.name = name
         if isinstance(content, list):
             content = content

fastNLP/core/fieldarray.py

@@ -1,23 +1,22 @@
 class Instance(object):
-    """An Instance is an example of data. It is the collection of Fields.
+    """An Instance is an example of data.
+        Example::
+            ins = Instance(field_1=[1, 1, 1], field_2=[2, 2, 2])
+            ins["field_1"]
+            >>[1, 1, 1]
+            ins.add_field("field_3", [3, 3, 3])
 
-    ::
-        Instance(field_1=[1, 1, 1], field_2=[2, 2, 2])
+        :param fields: a dict of (str: list).
 
     """
 
     def __init__(self, **fields):
-        """
-
-        :param fields: a dict of (str: list).
-        """
         self.fields = fields
 
     def add_field(self, field_name, field):
         """Add a new field to the instance.
 
         :param field_name: str, the name of the field.
-        :param field:
         """
         self.fields[field_name] = field
 

fastNLP/core/instance.py

@@ -13,6 +13,9 @@
 
 
 class LossBase(object):
+    """Base class for all losses.
+
+    """
     def __init__(self):
         self.param_map = {}
         self._checked = False
@@ -68,10 +71,9 @@ def _init_param_map(self, key_map=None, **kwargs):
         #                     f"positional argument.).")
 
     def _fast_param_map(self, pred_dict, target_dict):
-        """
-
-        Only used as inner function. When the pred_dict, target is unequivocal. Don't need users to pass key_map.
+        """Only used as inner function. When the pred_dict, target is unequivocal. Don't need users to pass key_map.
             such as pred_dict has one element, target_dict has one element
+
         :param pred_dict:
         :param target_dict:
         :return: dict, if dict is not {}, pass it to self.evaluate. Otherwise do mapping.
@@ -265,27 +267,22 @@ def _prepare_losser(losser):
 
 
 def squash(predict, truth, **kwargs):
-    """To reshape tensors in order to fit loss functions in pytorch
-
-    :param predict	: Tensor, model output
-    :param truth	: Tensor, truth from dataset
-    :param **kwargs : extra arguments
+    """To reshape tensors in order to fit loss functions in PyTorch.
 
+    :param predict: Tensor, model output
+    :param truth: Tensor, truth from dataset
+    :param **kwargs: extra arguments
     :return predict , truth: predict & truth after processing
     """
     return predict.view(-1, predict.size()[-1]), truth.view(-1, )
 
 
 def unpad(predict, truth, **kwargs):
-    """To process padded sequence output to get true loss
-    Using pack_padded_sequence() method
-    This method contains squash()
+    """To process padded sequence output to get true loss.
 
-    :param predict	: Tensor, [batch_size , max_len , tag_size]
-    :param truth	: Tensor, [batch_size , max_len]
-    :param **kwargs : extra arguments, kwargs["lens"] is expected to be exsist
-        kwargs["lens"] : list or LongTensor, [batch_size]
-                      the i-th element is true lengths of i-th sequence
+    :param predict: Tensor, [batch_size , max_len , tag_size]
+    :param truth: Tensor, [batch_size , max_len]
+    :param kwargs: kwargs["lens"] is a list or LongTensor, with size [batch_size]. The i-th element is true lengths of i-th sequence.
 
     :return predict , truth: predict & truth after processing
     """
@@ -299,15 +296,11 @@ def unpad(predict, truth, **kwargs):
 
 
 def unpad_mask(predict, truth, **kwargs):
-    """To process padded sequence output to get true loss
-    Using mask() method
-    This method contains squash()
+    """To process padded sequence output to get true loss.
 
-    :param predict	: Tensor, [batch_size , max_len , tag_size]
-    :param truth	: Tensor, [batch_size , max_len]
-    :param **kwargs : extra arguments, kwargs["lens"] is expected to be exsist
-        kwargs["lens"] : list or LongTensor, [batch_size]
-                      the i-th element is true lengths of i-th sequence
+    :param predict: Tensor, [batch_size , max_len , tag_size]
+    :param truth: Tensor, [batch_size , max_len]
+    :param kwargs: kwargs["lens"] is a list or LongTensor, with size [batch_size]. The i-th element is true lengths of i-th sequence.
 
     :return predict , truth: predict & truth after processing
     """
@@ -318,14 +311,11 @@ def unpad_mask(predict, truth, **kwargs):
 
 
 def mask(predict, truth, **kwargs):
-    """To select specific elements from Tensor
-    This method contains squash()
+    """To select specific elements from Tensor. This method calls ``squash()``.
 
-    :param predict	: Tensor, [batch_size , max_len , tag_size]
-    :param truth	: Tensor, [batch_size , max_len]
-    :param **kwargs : extra arguments, kwargs["mask"] is expected to be exsist
-        kwargs["mask"] : ByteTensor, [batch_size , max_len]
-                      the mask Tensor , the position that is 1 will be selected
+    :param predict: Tensor, [batch_size , max_len , tag_size]
+    :param truth: Tensor, [batch_size , max_len]
+    :param **kwargs: extra arguments, kwargs["mask"]: ByteTensor, [batch_size , max_len], the mask Tensor. The position that is 1 will be selected.
 
     :return predict , truth: predict & truth after processing
     """
@@ -343,13 +333,11 @@ def mask(predict, truth, **kwargs):
 
 
 def make_mask(lens, tar_len):
-    """to generate a mask that select [:lens[i]] for i-th element
-    embezzle from fastNLP.models.sequence_modeling.seq_mask
-
-    :param lens		: list or LongTensor, [batch_size]
-    :param tar_len	: int
+    """To generate a mask over a sequence.
 
-    :return mask 	: ByteTensor
+    :param lens: list or LongTensor, [batch_size]
+    :param tar_len: int
+    :return mask: ByteTensor
     """
     lens = torch.LongTensor(lens)
     mask = [torch.ge(lens, i + 1) for i in range(tar_len)]