GH-43352: [Docs][Python] Add all tensor classes documentation

docs/source/index.rst

@@ -115,6 +115,16 @@ Implementations
    Rust <https://docs.rs/crate/arrow/>
    status
 
+Tensors
+-------
+
+.. _toc.tensors:
+
+.. toctree::
+   :maxdepth: 2
+
+   <python/api/tensors.rst>
+
 Examples
 --------
 
@@ -127,3 +137,4 @@ Examples
    Java cookbook <https://arrow.apache.org/cookbook/java/>
    Python cookbook <https://arrow.apache.org/cookbook/py/>
    R cookbook <https://arrow.apache.org/cookbook/r/>
+

docs/source/python/api/tables.rst

@@ -54,12 +54,7 @@ Dataframe Interchange Protocol
 
    interchange.from_dataframe
 
-.. _api.tensor:
+See Also
+--------
 
-Tensors
--------
-
-.. autosummary::
-   :toctree: ../generated/
-
-   Tensor
+For information about tensors, refer to :doc:`tensors`

docs/source/python/api/tensors.rst

@@ -0,0 +1,114 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements.  See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership.  The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License.  You may obtain a copy of the License at
+
+..   http://www.apache.org/licenses/LICENSE-2.0
+
+.. Unless required by applicable law or agreed to in writing,
+.. software distributed under the License is distributed on an
+.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+.. KIND, either express or implied.  See the License for the
+.. specific language governing permissions and limitations
+.. under the License.
+
+.. currentmodule:: pyarrow
+
+.. _api.tensor:
+
+Tensors
+=======
+
+PyArrow supports both dense and sparse tensors. Dense tensors store all data values explicitly, while sparse tensors represent only the non-zero elements and their locations, making them efficient for storage and computation.
+
+Dense Tensors
+^^^^^^^^^^^^^
+
+.. autosummary::
+   :toctree: ../generated/
+
+   Tensor
+
+Sparse Tensors
+^^^^^^^^^^^^^
+
+PyArrow supports the following sparse tensor formats:
+
+.. autosummary::
+   :toctree: ../generated/
+
+   SparseCOOTensor
+   SparseCSRMatrix
+   SparseCSCMatrix
+   SparseCSFTensor
+
+"""SparseCOOTensor"""
+
+The ``SparseCOOTensor`` represents a sparse tensor in Coordinate (COO) format, where non-zero elements are stored as tuples of row and column indices.
+
+Example:
+.. code-block:: python
+
+   import pyarrow as pa
+
+   indices = pa.array([[0, 0], [1, 2]])
+   data = pa.array([1, 2])
+   shape = (2, 3)
+
+   tensor = pa.SparseCOOTensor(indices, data, shape)
+   print(tensor.to_dense())
+
+"""SparseCSRMatrix"""
+
+The ``SparseCSRMatrix`` represents a sparse matrix in Compressed Sparse Row (CSR) format. This format is useful for matrix-vector multiplication.
+
+Example:
+.. code-block:: python
+
+   import pyarrow as pa
+
+   data = pa.array([1, 2, 3])
+   indptr = pa.array([0, 2, 3])
+   indices = pa.array([0, 2, 1])
+   shape = (2, 3)
+
+   sparse_matrix = pa.SparseCSRMatrix.from_numpy(data, indptr, indices, shape)
+   print(sparse_matrix)
+
+"""SparseCSCMatrix"""
+
+The ``SparseCSCMatrix`` represents a sparse matrix in Compressed Sparse Column (CSC) format, where data is stored by columns.
+
+Example:
+.. code-block:: python
+
+   import pyarrow as pa
+
+   data = pa.array([1, 2, 3])
+   indptr = pa.array([0, 1, 3])
+   indices = pa.array([0, 1, 2])
+   shape = (3, 2)
+
+   sparse_matrix = pa.SparseCSCMatrix.from_numpy(data, indptr, indices, shape)
+   print(sparse_matrix)
+
+"""SparseCSFTensor"""
+
+The ``SparseCSFTensor`` represents a sparse tensor in Compressed Sparse Fiber (CSF) format, which is a generalization of the CSR format for higher dimensions.
+
+Example:
+.. code-block:: python
+
+   import pyarrow as pa
+
+   data = pa.array([1, 2, 3])
+   indptr = [pa.array([0, 1, 3]), pa.array([0, 2, 3])]
+   indices = [pa.array([0, 1]), pa.array([0, 1, 2])]
+   shape = (2, 3, 2)
+
+   sparse_tensor = pa.SparseCSFTensor.from_numpy(data, indptr, indices, shape)
+   print(sparse_tensor)
+

python/pyarrow/tensor.pxi

@@ -595,7 +595,25 @@ shape: {0.shape}""".format(self)
 
 cdef class SparseCSRMatrix(_Weakrefable):
     """
-    A sparse CSR matrix.
+    SparseCSRMatrix represents a sparse matrix in Compressed Sparse Row (CSR) format.
+
+    Attributes:
+        indptr : array
+            Index pointer array.
+        indices : array
+            Column indices of the corresponding non-zero values.
+        shape : tuple
+            Shape of the matrix.
+        dim_names : list, optional
+            Names of the dimensions.
+
+    Example:
+        >>> import pyarrow as pa
+        >>> indptr = pa.array([0, 2, 3])
+        >>> indices = pa.array([0, 2, 1])
+        >>> shape = (2, 3)
+        >>> tensor = pa.SparseCSRMatrix(indptr, indices, shape)
+        >>> print(tensor)
     """
 
     def __init__(self):