Fix PR10 error and Clean up docstrings from functions related to RT05 errors (#25132)

Author: thoo

ci/code_checks.sh

@@ -241,8 +241,8 @@ fi
 ### DOCSTRINGS ###
 if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
 
-    MSG='Validate docstrings (GL06, GL07, GL09, SS04, PR03, PR05, PR10, EX04, RT04, RT05, SS05, SA05)' ; echo $MSG
-    $BASE_DIR/scripts/validate_docstrings.py --format=azure --errors=GL06,GL07,GL09,SS04,PR03,PR04,PR05,EX04,RT04,RT05,SS05,SA05
+    MSG='Validate docstrings (GL06, GL07, GL09, SS04, SS05, PR03, PR04, PR05, PR10, EX04, RT04, RT05, SA05)' ; echo $MSG
+    $BASE_DIR/scripts/validate_docstrings.py --format=azure --errors=GL06,GL07,GL09,SS04,SS05,PR03,PR04,PR05,PR10,EX04,RT04,RT05,SA05
     RET=$(($RET + $?)) ; echo $MSG "DONE"
 
 fi

pandas/core/algorithms.py

@@ -288,10 +288,15 @@ def unique(values):
 
     Returns
     -------
-    unique values.
-      If the input is an Index, the return is an Index
-      If the input is a Categorical dtype, the return is a Categorical
-      If the input is a Series/ndarray, the return will be an ndarray.
+    numpy.ndarray or ExtensionArray
+
+        The return can be:
+
+        * Index : when the input is an Index
+        * Categorical : when the input is a Categorical dtype
+        * ndarray : when the input is a Series/ndarray
+
+        Return numpy.ndarray or ExtensionArray.
 
     See Also
     --------

pandas/core/arrays/categorical.py

@@ -1289,7 +1289,7 @@ def __array__(self, dtype=None):
 
         Returns
         -------
-        values : numpy array
+        numpy.array
             A numpy array of either the specified dtype or,
             if dtype==None (default), the same dtype as
             categorical.categories.dtype.
@@ -1499,9 +1499,9 @@ def get_values(self):
 
         Returns
         -------
-        values : numpy array
+        numpy.array
             A numpy array of the same dtype as categorical.categories.dtype or
-            Index if datetime / periods
+            Index if datetime / periods.
         """
         # if we are a datetime and period index, return Index to keep metadata
         if is_datetimelike(self.categories):
@@ -1540,7 +1540,7 @@ def argsort(self, *args, **kwargs):
 
         Returns
         -------
-        argsorted : numpy array
+        numpy.array
 
         See Also
         --------
@@ -1593,7 +1593,7 @@ def sort_values(self, inplace=False, ascending=True, na_position='last'):
 
         Returns
         -------
-        y : Categorical or None
+        Categorical or None
 
         See Also
         --------
@@ -1667,7 +1667,7 @@ def _values_for_rank(self):
 
         Returns
         -------
-        numpy array
+        numpy.array
 
         """
         from pandas import Series
@@ -1695,7 +1695,7 @@ def ravel(self, order='C'):
 
         Returns
         -------
-        raveled : numpy array
+        numpy.array
         """
         return np.array(self)
 

pandas/core/arrays/datetimelike.py

@@ -144,7 +144,7 @@ def strftime(self, date_format):
         Return an Index of formatted strings specified by date_format, which
         supports the same string format as the python standard library. Details
         of the string format can be found in `python string format
-        doc <%(URL)s>`__
+        doc <%(URL)s>`__.
 
         Parameters
         ----------
@@ -748,7 +748,7 @@ def _maybe_mask_results(self, result, fill_value=iNaT, convert=None):
         mask the result if needed, convert to the provided dtype if its not
         None
 
-        This is an internal routine
+        This is an internal routine.
         """
 
         if self._hasnans:
@@ -1047,7 +1047,7 @@ def _sub_period_array(self, other):
         Returns
         -------
         result : np.ndarray[object]
-            Array of DateOffset objects; nulls represented by NaT
+            Array of DateOffset objects; nulls represented by NaT.
         """
         if not is_period_dtype(self):
             raise TypeError("cannot subtract {dtype}-dtype from {cls}"

pandas/core/frame.py

@@ -2696,7 +2696,7 @@ def get_value(self, index, col, takeable=False):
 
         Returns
         -------
-        scalar value
+        scalar
         """
 
         warnings.warn("get_value is deprecated and will be removed "
@@ -2736,7 +2736,7 @@ def set_value(self, index, col, value, takeable=False):
         ----------
         index : row label
         col : column label
-        value : scalar value
+        value : scalar
         takeable : interpret the index/col as indexers, default False
 
         Returns
@@ -6896,7 +6896,7 @@ def round(self, decimals=0, *args, **kwargs):
 
         Returns
         -------
-        DataFrame :
+        DataFrame
             A DataFrame with the affected columns rounded to the specified
             number of decimal places.
 
@@ -7000,6 +7000,7 @@ def corr(self, method='pearson', min_periods=1):
             * spearman : Spearman rank correlation
             * callable: callable with input two 1d ndarrays
                 and returning a float
+
                 .. versionadded:: 0.24.0
 
         min_periods : int, optional

pandas/core/generic.py

@@ -2807,21 +2807,25 @@ def to_latex(self, buf=None, columns=None, col_space=None, header=True,
             defaults to 'ascii' on Python 2 and 'utf-8' on Python 3.
         decimal : str, default '.'
             Character recognized as decimal separator, e.g. ',' in Europe.
+
             .. versionadded:: 0.18.0
         multicolumn : bool, default True
             Use \multicolumn to enhance MultiIndex columns.
             The default will be read from the config module.
+
             .. versionadded:: 0.20.0
         multicolumn_format : str, default 'l'
             The alignment for multicolumns, similar to `column_format`
             The default will be read from the config module.
+
             .. versionadded:: 0.20.0
         multirow : bool, default False
             Use \multirow to enhance MultiIndex rows. Requires adding a
             \usepackage{multirow} to your LaTeX preamble. Will print
             centered labels (instead of top-aligned) across the contained
             rows, separating groups via clines. The default will be read
             from the pandas config module.
+
             .. versionadded:: 0.20.0
 
         Returns
@@ -4948,11 +4952,15 @@ def pipe(self, func, *args, **kwargs):
 
     Returns
     -------
-    DataFrame, Series or scalar
-        If DataFrame.agg is called with a single function, returns a Series
-        If DataFrame.agg is called with several functions, returns a DataFrame
-        If Series.agg is called with single function, returns a scalar
-        If Series.agg is called with several functions, returns a Series.
+    scalar, Series or DataFrame
+
+        The return can be:
+
+        * scalar : when Series.agg is called with single function
+        * Series : when DataFrame.agg is called with a single function
+        * DataFrame : when DataFrame.agg is called with several functions
+
+        Return scalar, Series or DataFrame.
 
     %(see_also)s
 
@@ -6879,11 +6887,15 @@ def asof(self, where, subset=None):
         -------
         scalar, Series, or DataFrame
 
-           Scalar : when `self` is a Series and `where` is a scalar.
-           Series: when `self` is a Series and `where` is an array-like,
-             or when `self` is a DataFrame and `where` is a scalar.
-           DataFrame : when `self` is a DataFrame and `where` is an
-             array-like.
+            The return can be:
+
+            * scalar : when `self` is a Series and `where` is a scalar
+            * Series: when `self` is a Series and `where` is an array-like,
+              or when `self` is a DataFrame and `where` is a scalar
+            * DataFrame : when `self` is a DataFrame and `where` is an
+              array-like
+
+            Return scalar, Series, or DataFrame.
 
         See Also
         --------

pandas/core/indexes/base.py

@@ -1443,7 +1443,7 @@ def sortlevel(self, level=None, ascending=True, sort_remaining=None):
 
         Returns
         -------
-        sorted_index : Index
+        Index
         """
         return self.sort_values(return_indexer=True, ascending=ascending)
 
@@ -1461,7 +1461,7 @@ def _get_level_values(self, level):
 
         Returns
         -------
-        values : Index
+        Index
             Calling object, as there is only one level in the Index.
 
         See Also
@@ -1506,7 +1506,7 @@ def droplevel(self, level=0):
 
         Returns
         -------
-        index : Index or MultiIndex
+        Index or MultiIndex
         """
         if not isinstance(level, (tuple, list)):
             level = [level]
@@ -1558,11 +1558,11 @@ def droplevel(self, level=0):
         Returns
         -------
         grouper : Index
-            Index of values to group on
+            Index of values to group on.
         labels : ndarray of int or None
-            Array of locations in level_index
+            Array of locations in level_index.
         uniques : Index or None
-            Index of unique values for level
+            Index of unique values for level.
         """
 
     @Appender(_index_shared_docs['_get_grouper_for_level'])
@@ -2972,9 +2972,10 @@ def _convert_listlike_indexer(self, keyarr, kind=None):
 
         Returns
         -------
-        tuple (indexer, keyarr)
-            indexer is an ndarray or None if cannot convert
-            keyarr are tuple-safe keys
+        indexer : numpy.ndarray or None
+            Return an ndarray or None if cannot convert.
+        keyarr : numpy.ndarray
+            Return tuple-safe keys.
         """
         if isinstance(keyarr, Index):
             keyarr = self._convert_index_indexer(keyarr)
@@ -3158,9 +3159,9 @@ def _reindex_non_unique(self, target):
         Returns
         -------
         new_index : pd.Index
-            Resulting index
+            Resulting index.
         indexer : np.ndarray or None
-            Indices of output values in original index
+            Indices of output values in original index.
 
         """
 

pandas/core/indexes/multi.py

@@ -61,7 +61,7 @@ def _codes_to_ints(self, codes):
         Returns
         ------
         int_keys : scalar or 1-dimensional array, of dtype uint64
-            Integer(s) representing one combination (each)
+            Integer(s) representing one combination (each).
         """
         # Shift the representation of each level by the pre-calculated number
         # of bits:
@@ -101,7 +101,7 @@ def _codes_to_ints(self, codes):
         Returns
         ------
         int_keys : int, or 1-dimensional array of dtype object
-            Integer(s) representing one combination (each)
+            Integer(s) representing one combination (each).
         """
 
         # Shift the representation of each level by the pre-calculated number
@@ -2195,7 +2195,7 @@ def reindex(self, target, method=None, level=None, limit=None,
         new_index : pd.MultiIndex
             Resulting index
         indexer : np.ndarray or None
-            Indices of output values in original index
+            Indices of output values in original index.
 
         """
         # GH6552: preserve names when reindexing to non-named target

pandas/core/series.py

@@ -1669,6 +1669,8 @@ def unique(self):
             * Sparse
             * IntegerNA
 
+        See Examples section.
+
         Examples
         --------
         >>> pd.Series([2, 1, 3, 3], name='A').unique()

pandas/io/excel/_base.py

@@ -510,7 +510,7 @@ class ExcelWriter(object):
     mode : {'w' or 'a'}, default 'w'
         File mode to use (write or append).
 
-    .. versionadded:: 0.24.0
+        .. versionadded:: 0.24.0
 
     Attributes
     ----------