docs(tensor): add more introduction about Tensor

GitOrigin-RevId: 4eba1e6c03

imperative/python/megengine/core/tensor/array_method.py

@@ -614,166 +614,21 @@ class ArrayMethodMixin(abc.ABC):
         return reshape_cpp(self, (-1,))
 
     def sum(self, axis=None, keepdims: bool = False):
-        r"""Returns the sum of each row of the input tensor in the given dimension ``axis``.
-
-        If ``axis`` is a list of axises, reduce over all of them.
-        If ``keepdims`` is ``True``, the shape of output tensor is the same as the input tensor,
-        except in the dimension(s) ``axis`` where it is of size 1.
-        Otherwise, ``axis`` is squeezed (see :func:`~.squeeze`).
-
-        Args:
-            axis: the dimension or dimensions to reduce.
-            keepdims: whether the output tensor has ndim retained or not.
-
-        Returns:
-            output tensor.
-
-        Examples:
-            .. testcode::
-
-               from megengine import tensor
-               a = tensor([False, True, True, False])
-               b = tensor([1.0, 2.0, 3.0, 4.0])
-               print(a.sum().numpy())
-               print(b.sum().numpy())
-
-            Outputs:
-
-            .. testoutput::
-
-               2
-               10.0
-        """
+        r"""See :func:`~.sum`."""
         return _reduce("sum")(self, axis, keepdims)
 
     def prod(self, axis=None, keepdims: bool = False):
-        r"""Returns the product of each row of the input tensor in the given dimension ``axis``.
-
-        If ``axis`` is a list of axises, reduce over all of them.
-        If ``keepdims`` is ``True``, the shape of output tensor is the same as the input tensor,
-        except in the dimension(s) ``axis`` where it is of size 1.
-        Otherwise, ``axis`` is squeezed (see :func:`~.squeeze`).
-
-        Args:
-            axis: the dimension or dimensions to reduce.
-            keepdims: whether the output tensor has ndim retained or not.
-
-        Returns:
-            output tensor.
-
-        Examples:
-            .. testcode::
-
-               from megengine import tensor
-               a = tensor([False, True, True, False])
-               b = tensor([1.0, 2.0, 3.0, 4.0])
-               print(a.prod().numpy())
-               print(b.prod().numpy())
-
-            Outputs:
-
-            .. testoutput::
-
-               0
-               24.0
-        """
+        r"""See :func:`~.prod`."""
         return _reduce("product")(self, axis, keepdims)
 
     def min(self, axis=None, keepdims: bool = False):
-        r"""Returns the min value of each row of the input tensor in the given dimension ``axis``.
-
-        If ``axis`` is a list of axises, reduce over all of them.
-        If ``keepdims`` is ``True``, the shape of output tensor is the same as the input tensor,
-        except in the dimension(s) ``axis`` where it is of size 1.
-        Otherwise, ``axis`` is squeezed (see :func:`~.squeeze`).
-
-        Args:
-            axis: the dimension or dimensions to reduce.
-            keepdims: whether the output tensor has ndim retained or not.
-
-        Returns:
-            output tensor.
-
-        Examples:
-            .. testcode::
-
-               from megengine import tensor
-               a = tensor([False, True, True, False])
-               b = tensor([1.0, 2.0, 3.0, 4.0])
-               print(a.min().numpy())
-               print(b.min().numpy())
-
-            Outputs:
-
-            .. testoutput::
-
-               False
-               1.0
-        """
+        r"""See :func:`~.min`."""
         return _reduce("min")(self, axis, keepdims)
 
     def max(self, axis=None, keepdims: bool = False):
-        r"""Returns the max value of each row of the input tensor in the given dimension ``axis``.
-
-        If ``axis`` is a list of axises, reduce over all of them.
-        If ``keepdims`` is ``True``, the shape of output tensor is the same as the input tensor,
-        except in the dimension(s) ``axis`` where it is of size 1.
-        Otherwise, ``axis`` is squeezed (see :func:`~.squeeze`).
-
-        Args:
-            axis: the dimension or dimensions to reduce.
-            keepdims: whether the output tensor has ndim retained or not.
-
-        Returns:
-            output tensor.
-
-        Examples:
-            .. testcode::
-
-               from megengine import tensor
-               a = tensor([False, True, True, False])
-               b = tensor([1.0, 2.0, 3.0, 4.0])
-               print(a.max().numpy())
-               print(b.max().numpy())
-
-            Outputs:
-
-            .. testoutput::
-
-               True
-               4.0
-        """
+        r"""See :func:`~.max`."""
         return _reduce("max")(self, axis, keepdims)
 
     def mean(self, axis=None, keepdims: bool = False):
-        r"""Returns the mean value of each row of the input tensor in the given dimension ``axis``.
-
-        If ``axis`` is a list of axises, reduce over all of them.
-        If ``keepdims`` is ``True``, the shape of output tensor is the same as the input tensor,
-        except in the dimension(s) ``axis`` where it is of size 1.
-        Otherwise, ``axis`` is squeezed (see :func:`~.squeeze`).
-
-        Args:
-            axis: the dimension or dimensions to reduce.
-            keepdims: whether the output tensor has ndim retained or not.
-
-        Returns:
-            output tensor.
-
-        Examples:
-            .. testcode::
-
-               from megengine import tensor
-               a = tensor([False, True, True, False])
-               b = tensor([1.0, 2.0, 3.0, 4.0])
-               print(a.mean().numpy())
-               print(b.mean().numpy())
-
-            Outputs:
-
-            .. testoutput::
-
-               0.5
-               2.5
-        """
+        r"""See :func:`~.mean`."""
         return _reduce("mean")(self, axis, keepdims)

imperative/python/megengine/tensor.py

@@ -27,13 +27,41 @@ logger = get_logger(__name__)
 class Tensor(_Tensor, ArrayMethodMixin):
     r"""A tensor object represents a multidimensional, homogeneous array of fixed-size items.
 
+    Tensor is the primary MegEngine data structure.
+    Data type(dtype) describes the format of each element, such as ``float32``, ``int8`` and so on,
+    see :ref:`tensor-dtype` for more details.
+    It is similar to :class:`numpy.ndarray` but not the same in the design.
+    For example, GPU devices can be used to store Tensors and execute calculations in MegEngine.
+    The concept of `view <https://numpy.org/doc/stable/reference/generated/numpy.ndarray.view.html>`_
+    does not exist in MegEngine so indexing and other behaviors might be different with NumPy.
+    All manipulations and operations on/between Tensors could be found in the :mod:`~.megengine.functional` module.
+    Keep in mind that they are **not in-place**, a new Tensor will always be returned and
+    the original data will remain constant.
+
+    For more information, refer to the :ref:`tensor-guide` topic.
+
     Args:
-        data(Tensor, :class:`~.numpy.ndarray`, :class:`list` or python number.): The value of returned Tensor.
-        dtype: The dtype of returned Tensor. Uses data's dtype if not specified.
-        device: The desired device of returned Tensor. Uses :func:`get_default_device` if not specified.
-        is_const: Whether make it a ``ImutableTensor`` in tracing mode.
+        data(Tensor, :class:`~.numpy.ndarray`, :class:`list` or Python number): 
+            The data used for construcing Tensor.
+            Tensor could be constructed from a Python :class:`list` / :class:`tuple` or sequence;
+            a NumPy :class:`~.numpy.ndarray` data structure; MegEngine builtin methods and so on.
+            Refer to :ref:`tensor-creation` for more details.
+
+        dtype(:attr:`~.Tensor.dtype`): The data type of returned Tensor. Infer from ``data`` if not specified.
+        device(:attr:`~.Tensor.device`): The desired device of returned Tensor. Uses :func:`get_default_device` if not specified.
+        is_const: Whether make it a ``ImutableTensor`` in tracing mode, refer to :class:`.jit.trace`.
         no_cache: Whether cache it for memory sharing.
         name: Used to improve convenience in graph operation on dumped model.
+
+    .. note::
+
+       There are some methods like :meth:`~.Tensor.reshape` / :meth:`~.Tensor.flatten` / 
+       :meth:`~.Tensor.transpose` / :meth:`~.Tensor.min` / :meth:`~.Tensor.max` /
+       :meth:`~.Tensor.mean` / :meth:`~.Tensor.sum` / :meth:`~.Tensor.prod` implemented
+       in ``Tensor`` class for convenience and historical reasons.
+       But other methods implemented in the :mod:`~.megengine.functional` module will not be added here anymore,
+       it is hard for maintaining and too many candidates will affect code completion experience.
+
     """
 
     grad = None