DOC: Update is_sparse docstring (pandas-dev#19983)

* BUG: Identify SparseDataFrame as sparse

The is_sparse function checks to see if
an array-like is spare by checking to see
if it is an instance of ABCSparseArray or
ABCSparseSeries. This commit adds
ABCSparseDataFrame to that list -- so it
can detect that a DataFrame (which is an
array-like object) is sparse.

Added a test for this.

* Revert "BUG: Identify SparseDataFrame as sparse"

This reverts commit 10dffd1.

The previous commit's change was not necessary.
Will add a docstring to clarify the behaviour of the method.

* DOC: Revise is_sparce docstring

Clean up the docstring for is_sparse so it confirms to the
documentation style guide.

Add additional examples and clarify that is_sparse
expect a 1-dimensional array-like.

* DOC: Adjust is_sparse docstring.

Responding to pull request comments.

Author: sechilds

pandas/core/dtypes/common.py

@@ -150,32 +150,59 @@ def is_object_dtype(arr_or_dtype):
 
 def is_sparse(arr):
     """
-    Check whether an array-like is a pandas sparse array.
+    Check whether an array-like is a 1-D pandas sparse array.
+
+    Check that the one-dimensional array-like is a pandas sparse array.
+    Returns True if it is a pandas sparse array, not another type of
+    sparse array.
 
     Parameters
     ----------
     arr : array-like
-        The array-like to check.
+        Array-like to check.
 
     Returns
     -------
-    boolean : Whether or not the array-like is a pandas sparse array.
+    bool
+        Whether or not the array-like is a pandas sparse array.
+
+    See Also
+    --------
+    DataFrame.to_sparse : Convert DataFrame to a SparseDataFrame.
+    Series.to_sparse : Convert Series to SparseSeries.
+    Series.to_dense : Return dense representation of a Series.
 
     Examples
     --------
-    >>> is_sparse(np.array([1, 2, 3]))
-    False
-    >>> is_sparse(pd.SparseArray([1, 2, 3]))
+    Returns `True` if the parameter is a 1-D pandas sparse array.
+
+    >>> is_sparse(pd.SparseArray([0, 0, 1, 0]))
     True
-    >>> is_sparse(pd.SparseSeries([1, 2, 3]))
+    >>> is_sparse(pd.SparseSeries([0, 0, 1, 0]))
     True
 
-    This function checks only for pandas sparse array instances, so
-    sparse arrays from other libraries will return False.
+    Returns `False` if the parameter is not sparse.
+
+    >>> is_sparse(np.array([0, 0, 1, 0]))
+    False
+    >>> is_sparse(pd.Series([0, 1, 0, 0]))
+    False
+
+    Returns `False` if the parameter is not a pandas sparse array.
 
     >>> from scipy.sparse import bsr_matrix
-    >>> is_sparse(bsr_matrix([1, 2, 3]))
+    >>> is_sparse(bsr_matrix([0, 1, 0, 0]))
     False
+
+    Returns `False` if the parameter has more than one dimension.
+
+    >>> df = pd.SparseDataFrame([389., 24., 80.5, np.nan],
+                                columns=['max_speed'],
+                                index=['falcon', 'parrot', 'lion', 'monkey'])
+    >>> is_sparse(df)
+    False
+    >>> is_sparse(df.max_speed)
+    True
     """
     from pandas.core.arrays.sparse import SparseDtype