[Sparse] Improve API docs (#4663)

* replace with pow

* autosummary for attributes

* revert accidental push

* revert accidental push

* added example
Co-authored-by: Israt Nisa <nisisrat@amazon.com>

docs/source/api/python/dgl.sparse_v0.rst

@@ -12,9 +12,88 @@ Sparse matrix class
 -------------------------
 .. currentmodule:: dgl.mock_sparse
 
-.. autoclass:: SparseMatrix
-	:members: shape, nnz, dtype, device, row, col, val, __call__, indices, coo, csr, csc, dense, t, T, transpose,
-            reduce, sum, smax, smin, smean, __neg__, inv, softmax, __matmul__
+.. class:: SparseMatrix
+
+    Class for creating a sparse matrix representation. The row and column indices of the sparse matrix can be the source
+    (row) and destination (column) indices of a homogeneous or heterogeneous graph.
+
+    There are a few ways to create a sparse matrix:
+
+    * In COO format using row and col indices, use :func:`create_from_coo`.
+    * In CSR format using row pointers and col indices, use :func:`create_from_csr`.
+    * In CSC format using col pointers and row indices, use :func:`create_from_csc`.
+
+    For example, we can create COO matrix as follows:
+
+    Case1: Sparse matrix with row and column indices without values.
+
+        >>> src = torch.tensor([1, 1, 2])
+        >>> dst = torch.tensor([2, 4, 3])
+        >>> A = create_from_coo(src, dst)
+        >>> A
+        SparseMatrix(indices=tensor([[1, 1, 2],
+                                     [2, 4, 3]]),
+                     values=tensor([1., 1., 1.]),
+                     shape=(3, 5), nnz=3)
+
+    Case2: Sparse matrix with scalar/vector values. Following example is with
+    vector data.
+
+        >>> val = torch.tensor([[1, 1], [2, 2], [3, 3]])
+        >>> A = create_from_coo(src, dst, val)
+        SparseMatrix(indices=tensor([[1, 1, 2],
+                                     [2, 4, 3]]),
+                     values=tensor([[1, 1],
+                                    [2, 2],
+                                    [3, 3]]),
+                     shape=(3, 5), nnz=3)
+
+    Similarly, we can create CSR matrix as follows:
+
+        >>> indptr = torch.tensor([0, 1, 2, 5])
+        >>> indices = torch.tensor([1, 2, 0, 1, 2])
+        >>> val = torch.tensor([[1, 1], [2, 2], [3, 3], [4, 4], [5, 5]])
+        >>> A = create_from_csr(indptr, indices, val)
+        >>> A
+        SparseMatrix(indices=tensor([[0, 1, 2, 2, 2],
+                [1, 2, 0, 1, 2]]),
+        values=tensor([[1, 1],
+                [2, 2],
+                [3, 3],
+                [4, 4],
+                [5, 5]]),
+        shape=(3, 3), nnz=5)
+
+Sparse matrix class attributes
+------------------------------
+
+.. autosummary::
+
+    SparseMatrix.shape
+    SparseMatrix.nnz
+    SparseMatrix.dtype
+    SparseMatrix.device
+    SparseMatrix.row
+    SparseMatrix.col
+    SparseMatrix.val
+    __call__
+    SparseMatrix.indices
+    SparseMatrix.coo
+    SparseMatrix.csr
+    SparseMatrix.csc
+    SparseMatrix.dense
+    SparseMatrix.t
+    SparseMatrix.T
+    SparseMatrix.transpose
+    SparseMatrix.reduce
+    SparseMatrix.sum
+    SparseMatrix.smax
+    SparseMatrix.smin
+    SparseMatrix.smean
+    SparseMatrix.__neg__
+    SparseMatrix.inv
+    SparseMatrix.softmax
+    SparseMatrix.__matmul__
 
 .. autosummary::
     :toctree: ../../generated/
@@ -28,8 +107,31 @@ Diagonal matrix class
 .. currentmodule:: dgl.mock_sparse
 
 .. autoclass:: DiagMatrix
-	:members: val, shape, __call__, nnz, dtype, device, as_sparse, t, T, transpose,
-            reduce, sum, smax, smin, smean, __neg__, inv, softmax, __matmul__
+
+Diagonal matrix class attributes
+--------------------------------
+
+.. autosummary::
+
+    DiagMatrix.val
+    DiagMatrix.shape
+    DiagMatrix.__call__
+    DiagMatrix.nnz
+    DiagMatrix.dtype
+    DiagMatrix.device
+    DiagMatrix.as_sparse
+    DiagMatrix.t
+    DiagMatrix.T
+    DiagMatrix.transpose
+    DiagMatrix.reduce
+    DiagMatrix.sum
+    DiagMatrix.smax
+    DiagMatrix.smin
+    DiagMatrix.smean
+    DiagMatrix.__neg__
+    DiagMatrix.inv
+    DiagMatrix.softmax
+    DiagMatrix.__matmul__
 
 .. autosummary::
     :toctree: ../../generated/