Add api docs zzk (#3587)

* add api docs

* fix docs

* add api doc in math_ops

* Change the theme to read_the_docs

* add equation docs in math_add

* add equation docs in sub, mul, addn

* add mod div tanh docs

* add gelu, relu docs

* add sigmoid unsorted_segment_sum api docs

* add unsorted_segment example docs

* add equal to greate_equal example docs

* add logical and example docs

* add other example docs, include squared difference

* add requirements of sphinx_rtd_theme

* delete the requirement of sphinx-material

* use make of format

* add optimizer docs

* add scheduler docs

* fix multiplier docs in warmup

* add api docs for math binary elementwise ops

* add math unary api docs

* fix docs about round

* add api docs for reduce mean

* add api docs for reduce ops

* fix code block for reduce ops

* fix math equation

* fix math equation erf

* add code example for layers

* fix docs in layers

* fix of format

* add warmup module in rst

* fix focs for sbp author:yaochi

* fix details in api docs

* add nn api docs and add optimizer_grad_clip module in rst

* fix details in api docs

* fix details in nn

* add prelu api docs

* add smooth l1 loss api docs

* add api docs for matmul

* add api docs for constant op

* fix docs format in RMSProp

* add api docs for array ops

* add docs for random ops

* add api docs for tensor buffer ops

* fix an error in instance_dims doc

* add api docs for tensor_list_ops

* fix annotation in image_decode

* fix of_format

* fix docs for gather_nd

* fix docs

* fix error in constant op

* fix conflict and little error

* fix index to indices
Co-authored-by: Ndoombeaker <later@usopp.net>
Co-authored-by: NShenghang Tsai <jackalcooper@gmail.com>
Co-authored-by: Noneflow-bot <69100618+oneflow-bot@users.noreply.github.com>

oneflow/python/ops/constant_op.py

@@ -35,6 +35,44 @@ def constant(
     shape: Optional[Sequence[int]] = None,
     name: Optional[str] = None,
 ) -> remote_blob_util.BlobDef:
+    """This operator creates a constant Blob. 
+
+    Args:
+        value (Union[int, float]): The constant value of Blob.
+        dtype (Optional[dtype_util.dtype], optional): The data type of Blob. Defaults to None.
+        shape (Optional[Sequence[int]], optional): The shape of Blob. Defaults to None.
+        name (Optional[str], optional): The name for the operation. Defaults to None.
+
+    Raises:
+        NotImplementedError: The data type of value should be int or float. 
+
+    Returns:
+        remote_blob_util.BlobDef: The result blob. 
+
+    For example: 
+
+    .. code-block:: python 
+
+        import oneflow as flow
+        import numpy as np
+        import oneflow.typing as tp
+
+
+        @flow.global_function()
+        def constant_Job() -> tp.Numpy:
+            constant_blob = flow.constant(value=1.5, 
+                                        shape=(1, 3, 3), 
+                                        dtype=flow.float)
+            return constant_blob
+
+
+        out = constant_Job()
+
+        # out [[[1.5 1.5 1.5]
+        #       [1.5 1.5 1.5]
+        #       [1.5 1.5 1.5]]]
+
+    """
     if name is None:
         name = id_util.UniqueStr("Constant_")
     assert value is not None
@@ -72,6 +110,37 @@ def constant_scalar(
     dtype: Optional[dtype_util.dtype] = None,
     name: Optional[str] = None,
 ) -> remote_blob_util.BlobDef:
+    """This operator creates a constant scalar Blob. 
+
+    Args:
+        value (Union[int, float]): The constant value of Blob.
+        dtype (Optional[dtype_util.dtype], optional): The data type of Blob. Defaults to None.
+        name (Optional[str], optional): The name for the operation. Defaults to None.
+
+    Returns:
+        remote_blob_util.BlobDef: The result blob. 
+
+    For example: 
+
+    .. code-block:: python 
+
+        import oneflow as flow
+        import numpy as np
+        import oneflow.typing as tp
+
+
+        @flow.global_function()
+        def constant_scalar_Job() -> tp.Numpy:
+            constant_scalar = flow.constant_scalar(value=2.5, 
+                                                dtype=flow.float)
+            return constant_scalar
+
+
+        out = constant_scalar_Job()
+
+        # out [2.5]
+
+    """
     return flow.constant(value, dtype=dtype, shape=[1])
 
 
@@ -82,6 +151,47 @@ def constant_like(
     dtype: Optional[dtype_util.dtype] = None,
     name: Optional[str] = None,
 ) -> remote_blob_util.BlobDef:
+    """This operator creates a constant Blob that has the same shape as `like`. 
+
+    Args:
+        like (remote_blob_util.BlobDef): A Blob. 
+        value (Union[int, float]): The constant value of Blob.
+        dtype (Optional[dtype_util.dtype], optional): The data type of Blob. Defaults to None.
+        name (Optional[str], optional): The name for the operation. Defaults to None.
+
+    Raises:
+        NotImplementedError: The data type of value should be int or float. 
+
+    Returns:
+        remote_blob_util.BlobDef: The result Blob. 
+
+    For example: 
+
+    .. code-block:: python 
+
+        import oneflow as flow
+        import numpy as np
+        import oneflow.typing as tp
+
+
+        @flow.global_function()
+        def constant_like_Job() -> tp.Numpy:
+            constant_blob = flow.constant(value=1.5, 
+                                        shape=(1, 3, 3), 
+                                        dtype=flow.float)
+            constant_like_blob = flow.constant_like(like=constant_blob, 
+                                                    value=5.5, 
+                                                    dtype=flow.float)
+            return constant_like_blob
+
+
+        out = constant_like_Job()
+
+        # out [[[5.5 5.5 5.5]
+        #       [5.5 5.5 5.5]
+        #       [5.5 5.5 5.5]]]
+
+    """
     op_conf = op_conf_util.OperatorConf()
     setattr(
         op_conf,
@@ -111,6 +221,42 @@ def ones_like(
     dtype: Optional[dtype_util.dtype] = None,
     name: Optional[str] = None,
 ) -> remote_blob_util.BlobDef:
+    """This operator creates a Blob with all elements set to `1` that has the same shape as `like`.
+
+    Args:
+        like (remote_blob_util.BlobDef): A Blob. 
+        dtype (Optional[dtype_util.dtype], optional): The data type of Blob. Defaults to None.
+        name (Optional[str], optional): The name for the operation. Defaults to None.
+
+    Returns:
+        remote_blob_util.BlobDef: The result Blob. 
+
+    For example: 
+
+    .. code-block:: python 
+
+        import oneflow as flow
+        import numpy as np
+        import oneflow.typing as tp
+
+
+        @flow.global_function()
+        def ones_like_Job() -> tp.Numpy:
+            constant_blob = flow.constant(value=1.5, 
+                                        shape=(1, 3, 3), 
+                                        dtype=flow.float)
+            ones_like_blob = flow.ones_like(like=constant_blob, 
+                                            dtype=flow.float)
+            return ones_like_blob
+
+
+        out = ones_like_Job()
+
+        # out [[[1. 1. 1.]
+        #       [1. 1. 1.]
+        #       [1. 1. 1.]]]
+
+    """
     return constant_like(like, 1, dtype=dtype, name=name)
 
 
@@ -120,4 +266,40 @@ def zeros_like(
     dtype: Optional[dtype_util.dtype] = None,
     name: Optional[str] = None,
 ) -> remote_blob_util.BlobDef:
+    """This operator creates a Blob that has the same shape as `like` whose all elements are set to `0`. 
+
+    Args:
+        like (remote_blob_util.BlobDef): A Blob. 
+        dtype (Optional[dtype_util.dtype], optional): The data type of Blob. Defaults to None.
+        name (Optional[str], optional): The name for the operation. Defaults to None.
+
+    Returns:
+        remote_blob_util.BlobDef: The result Blob. 
+
+    For example: 
+
+    .. code-block:: python 
+
+        import oneflow as flow
+        import numpy as np
+        import oneflow.typing as tp
+
+
+        @flow.global_function()
+        def zeros_like_Job() -> tp.Numpy:
+            constant_blob = flow.constant(value=1.5, 
+                                        shape=(1, 3, 3), 
+                                        dtype=flow.float)
+            zeros_like_blob = flow.zeros_like(like=constant_blob, 
+                                            dtype=flow.float)
+            return zeros_like_blob
+
+
+        out = zeros_like_Job()
+
+        # out [[[0. 0. 0.]
+        #       [0. 0. 0.]
+        #       [0. 0. 0.]]]
+
+    """
     return constant_like(like, 0, dtype=dtype, name=name)

oneflow/python/ops/optimizer.py

@@ -1239,17 +1239,23 @@ class RMSProp(Optimizer):
     This algorithm uses mean squared gradient to adjust the learning rate.
 
     The equation of parameters updating is:
-        .. math::
-            & S_t = \beta_1*S_{t-1} + (1-\beta_1)*grad \odot grad
-            & param_{new} = param_{old} - \frac{learning\_rate}{\sqrt{S_t+\epsilon}} \odot grad
+    
         if centered:
+    
             .. math::
+    
                 & mg_t = mg * \beta_1 + (1 - \beta_1) * grad
+    
                 & denom_t = S_t - mg_t * mg_t
+        
         else:
+    
             .. math::
+    
                 denom_t = S_t
+
         .. math::
+
             param_{new} = param_{old} - \frac{learning\_rate}{\sqrt{denom_t+\epsilon}} \odot grad
 
     Args:

oneflow/python/ops/random_ops.py

@@ -31,6 +31,44 @@ def Bernoulli(
     dtype: Optional[dtype_util.dtype] = None,
     name: str = "Bernoulli",
 ) -> remote_blob_util.BlobDef:
+    """This operator returns a Blob with binaray random numbers (0 / 1) from a Bernoulli distribution. 
+
+    Args:
+        x (remote_blob_util.BlobDef): The input Blob. 
+        seed (Optional[int], optional): The random seed. Defaults to None.
+        dtype (Optional[dtype_util.dtype], optional): The data type. Defaults to None.
+        name (str, optional): The name for the operation. Defaults to "Bernoulli".
+
+    Returns:
+        remote_blob_util.BlobDef: The result Blob. 
+
+    For example: 
+
+    .. code-block:: python 
+
+        import oneflow as flow
+        import numpy as np
+        import oneflow.typing as tp
+
+
+        @flow.global_function()
+        def bernoulli_Job(x: tp.Numpy.Placeholder(shape=(3, 3), dtype=flow.float32),
+        ) -> tp.Numpy:
+            out = flow.random.bernoulli(x)
+            return out
+
+
+        x = np.array([[0.25, 0.45, 0.3], 
+                    [0.55, 0.32, 0.13], 
+                    [0.75, 0.15, 0.1]]).astype(np.float32)
+        out = bernoulli_Job(x)
+
+        # Because our random seed is not fixed, so the return value is different each time. 
+        # out [[1. 0. 0.]
+        #      [0. 0. 1.]
+        #      [0. 0. 0.]]
+
+    """
     assert isinstance(name, str)
     if dtype is None:
         dtype = x.dtype

oneflow/python/ops/tensor_buffer_ops.py

@@ -31,15 +31,42 @@ def tensor_buffer_to_tensor(
     instance_shape: Sequence[int],
     name: Optional[str] = None,
 ) -> BlobDef:
-    r"""Converts the Blob type to TensorBuffer.
+    r"""This operator converts the Blob's type from TensorBuffer to Tensor. 
+    Some operator's output data type is `TensorBuffer`, you can use this operator to convert back
+    to `Tensor`. 
 
     Args:
-        x: Input `Blob`.
-        dtype: The destination dtype.
-        instance_shape: The shape of each TensorBuffer.
-        name: Name for the operator.
+        x (BlobDef): Input `Blob`.
+        dtype (dtype_util.dtype): The data dtype.
+        instance_shape (Sequence[int]): The shape of each TensorBuffer instance.
+        name (Optional[str], optional): The name for the operation. Defaults to None.
+
     Returns:
-        A `Blob`.
+        BlobDef: A `Blob`.
+
+    For example: 
+
+    .. code-block:: python 
+
+        import oneflow as flow
+        import numpy as np
+        import oneflow.typing as tp
+
+
+        @flow.global_function()
+        def tensor_buffer_to_tensor_Job(x: tp.Numpy.Placeholder(shape=(4, 16, 64, 64), dtype=flow.float32),
+        ) -> tp.Numpy:
+            x = flow.tensor_to_tensor_buffer(x, 
+                                            instance_dims=2)
+            return flow.tensor_buffer_to_tensor(x, 
+                                                instance_shape=(64, 64), 
+                                                dtype=flow.float)
+
+        x = np.random.randn(4, 16, 64, 64).astype(np.float32)
+        out = tensor_buffer_to_tensor_Job(x)
+
+        # out.shape (4, 16, 64, 64)
+    
     """
     if name is None:
         name = id_util.UniqueStr("TensorBufferToTensor_")
@@ -60,14 +87,39 @@ def tensor_buffer_to_tensor(
 def tensor_to_tensor_buffer(
     x: BlobDef, instance_dims: int, name: Optional[str] = None,
 ) -> BlobDef:
-    r"""Converts the TensorBuffer Blob to dense Tensor.
+    r"""This operator converts the Blob's type from Tensor to TensorBuffer. 
 
     Args:
-        x: Input `Blob`.
-        instance_dims: The number of dimensions to convert to TensorBuffer.
-        name: Name for the operator.
+        x (BlobDef): Input `Blob`.
+        instance_dims (int): The dimensions of dynamic tensor instance. 
+        name (Optional[str], optional): The name for the operation. Defaults to None.
+
     Returns:
-        A `Blob`.
+        BlobDef: The result Blob. 
+
+    For example: 
+
+    .. code-block:: python 
+
+        import oneflow as flow
+        import numpy as np
+        import oneflow.typing as tp
+
+
+        @flow.global_function()
+        def tensor_buffer_to_tensor_Job(x: tp.Numpy.Placeholder(shape=(4, 16, 64, 64), dtype=flow.float32),
+        ) -> tp.Numpy:
+            x = flow.tensor_to_tensor_buffer(x, 
+                                            instance_dims=2)
+            return flow.tensor_buffer_to_tensor(x, 
+                                                instance_shape=(64, 64), 
+                                                dtype=flow.float)
+
+        x = np.random.randn(4, 16, 64, 64).astype(np.float32)
+        out = tensor_buffer_to_tensor_Job(x)
+
+        # out.shape (4, 16, 64, 64)
+
     """
     if name is None:
         name = id_util.UniqueStr("TensorToTensorBuffer_")

oneflow/python/ops/tensor_list_ops.py

@@ -30,6 +30,41 @@ from typing import Optional, Sequence, Tuple
 def tensor_list_to_tensor_buffer(
     input: remote_blob_util.BlobDef, name: Optional[str] = None
 ) -> remote_blob_util.BlobDef:
+    """This operator converts `TensorList` to `TensorBuffer`. 
+
+    Args:
+        input (remote_blob_util.BlobDef): The input `TensorList`. 
+        name (Optional[str], optional): The name for the operation. Defaults to None.
+
+    Returns:
+        remote_blob_util.BlobDef: The result Blob. 
+
+    For example: 
+
+    .. code-block:: python 
+
+        import oneflow as flow
+        import numpy as np
+        import oneflow.typing as tp
+
+        func_config = flow.FunctionConfig()
+        func_config.default_data_type(flow.float)
+        func_config.default_logical_view(flow.scope.mirrored_view())
+        @flow.global_function(function_config=func_config)
+        def tensorList_to_tensorBuffer_Job(x: tp.ListListNumpy.Placeholder(shape=(2, 5, 4), dtype=flow.float32),
+        ) -> tp.ListListNumpy:
+            x = flow.tensor_list_to_tensor_buffer(input=x)
+            return flow.tensor_buffer_to_tensor_list(x, 
+                                                    shape=(5, 4), 
+                                                    dtype=flow.float32)
+
+        x = np.random.rand(1, 3, 2).astype(np.float32)
+        y = np.random.rand(1, 2, 2).astype(np.float32)
+        out = tensorList_to_tensorBuffer_Job([[x, y]])
+
+        # out[0][0].shape (1, 3, 2)
+
+    """
     if name is None:
         name = id_util.UniqueStr("TensorListToBuffer_")
 
@@ -52,6 +87,42 @@ def tensor_buffer_to_tensor_list(
     dtype: dtype_util.dtype,
     name: Optional[str] = None,
 ) -> remote_blob_util.BlobDef:
+    """This operator converts `TensorBuffer` to `TensorList`. 
+
+    Args:
+        input (remote_blob_util.BlobDef): The input Tensor Buffer. 
+        shape (Sequence[int]): The shape of input Tensor Buffer. 
+        dtype (dtype_util.dtype): The data type. 
+        name (Optional[str], optional): The name for the operation. Defaults to None.
+
+    Returns:
+        remote_blob_util.BlobDef: The result Blob. 
+    
+    For example: 
+
+    .. code-block:: python 
+
+        import oneflow as flow
+        import numpy as np
+        import oneflow.typing as tp
+
+
+        @flow.global_function()
+        def tensorBuffer_to_tensorList_Job(x: tp.Numpy.Placeholder(shape=(4, 16, 64, 64), dtype=flow.float32),
+        ) -> tp.ListListNumpy:
+            x = flow.tensor_to_tensor_buffer(x, 
+                                            instance_dims=3)
+            out = flow.tensor_buffer_to_tensor_list(input=x, 
+                                                    shape=(16, 64, 64), 
+                                                    dtype=flow.float32)
+            return out
+
+        x = np.random.randn(4, 16, 64, 64).astype(np.float32)
+        out = tensorBuffer_to_tensorList_Job(x)
+
+        # out[0][0].shape (1, 16, 64, 64)
+
+    """
     if name is None:
         name = id_util.UniqueStr("TensorBufferToList_")
 
@@ -77,6 +148,42 @@ def tensor_buffer_to_tensor_list(
 def tensor_list_split(
     input_tensor_list: remote_blob_util.BlobDef, name: Optional[str] = None
 ) -> Tuple[remote_blob_util.BlobDef]:
+    """This operator splits the input `TensorList`. 
+
+    Args:
+        input_tensor_list (remote_blob_util.BlobDef): The input `TensorList`. 
+        name (Optional[str], optional): The name for the operation. Defaults to None.
+
+    Returns:
+        Tuple[remote_blob_util.BlobDef]: A Tuple of `ListNumpy`. 
+
+    For example: 
+
+    .. code-block:: python 
+
+        import oneflow as flow
+        import numpy as np
+        import oneflow.typing as tp
+        from typing import Tuple
+
+
+        func_config = flow.FunctionConfig()
+        func_config.default_data_type(flow.float)
+        func_config.default_logical_view(flow.scope.mirrored_view())
+        @flow.global_function(function_config=func_config)
+        def tensorList_split_Job(x: tp.ListListNumpy.Placeholder(shape=(2, 5, 4), dtype=flow.float32),
+        ) -> Tuple[tp.ListNumpy, tp.ListNumpy]:
+            return flow.tensor_list_split(x)
+
+
+        x = np.random.rand(1, 3, 2).astype(np.float32)
+        y = np.random.rand(1, 2, 2).astype(np.float32)
+        out = tensorList_split_Job([[x, y]])
+
+        # out[0][0].shape (3, 2)
+        # out[1][0].shape (2, 2)
+
+    """
     if name is None:
         name = id_util.UniqueStr("TensorListSplit_")
 

oneflow/python/ops/user_data_ops.py

@@ -1030,6 +1030,7 @@ def image_decode(
         import numpy as np
         from PIL import Image
 
+
         def _of_image_decode(images):
             image_files = [open(im, "rb") for im in images]
             images_bytes = [imf.read() for imf in image_files]
@@ -1044,7 +1045,7 @@ def image_decode(
             @flow.global_function(function_config=func_config)
             def image_decode_job(
                 images_def: tp.ListListNumpy.Placeholder(shape=static_shape, dtype=flow.int8)
-            ):
+            )->tp.ListListNumpy:
                 # convert to tensor buffer
                 images_buffer = flow.tensor_list_to_tensor_buffer(images_def)
                 decoded_images_buffer = flow.image_decode(images_buffer)
@@ -1057,8 +1058,9 @@ def image_decode(
             images_np_arr = [
                 np.frombuffer(bys, dtype=np.byte).reshape(1, -1) for bys in images_bytes
             ]
-            decoded_images = image_decode_job([images_np_arr]).get().numpy_lists()
+            decoded_images = image_decode_job([images_np_arr])
             return decoded_images[0]
+            
 
         if __name__ == "__main__": 
             img = _of_image_decode(['./img/1.jpg'])

oneflow/python/ops/watch.py

@@ -240,6 +240,8 @@ def WatchDiff(
         import numpy as np 
 
 
+        BATCH_SIZE = 20
+
         def watch_diff_handler(blob: tp.Numpy):
             print("watch_diff_handler:", blob)