DOCS: fix docstring validation errors for pandas.Series (#59602)

* DOCS: pandas.Series.prod + pandas.Series.product RT03 docstring validation error fixed

* DOCS: pandas.Series.pop SA01 + pandas.Series.reorder_levels RT03/SA01 docstring validation error fixed

* DOCS: pandas.Series.list.__getitem__ + pandas.Series.list.flatten + pandas.Series.list.len SA01 docstring validation error fixed

* DOCS: pandas.Series.sparse.density SA01 docstring validation error fixed

* DOCS: pandas.Series.gt + pandas.Series.lt + pandas.Series.ne SA01 docstring validation error fixed

* linting issues leftover from docstring validation fixes resolved

Author: hlakams

ci/code_checks.sh

@@ -133,20 +133,9 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         -i "pandas.Series.dt.tz_convert PR01,PR02" \
         -i "pandas.Series.dt.tz_localize PR01,PR02" \
         -i "pandas.Series.dt.unit GL08" \
-        -i "pandas.Series.gt SA01" \
-        -i "pandas.Series.list.__getitem__ SA01" \
-        -i "pandas.Series.list.flatten SA01" \
-        -i "pandas.Series.list.len SA01" \
-        -i "pandas.Series.lt SA01" \
-        -i "pandas.Series.ne SA01" \
         -i "pandas.Series.pad PR01,SA01" \
-        -i "pandas.Series.pop SA01" \
-        -i "pandas.Series.prod RT03" \
-        -i "pandas.Series.product RT03" \
-        -i "pandas.Series.reorder_levels RT03,SA01" \
         -i "pandas.Series.sem PR01,RT03,SA01" \
         -i "pandas.Series.sparse PR01,SA01" \
-        -i "pandas.Series.sparse.density SA01" \
         -i "pandas.Series.sparse.fill_value SA01" \
         -i "pandas.Series.sparse.from_coo PR07,SA01" \
         -i "pandas.Series.sparse.npoints SA01" \

pandas/core/arrays/arrow/accessors.py

@@ -92,6 +92,12 @@ def len(self) -> Series:
         pandas.Series
             The length of each list.
 
+        See Also
+        --------
+        str.len : Python built-in function returning the length of an object.
+        Series.size : Returns the length of the Series.
+        StringMethods.len : Compute the length of each element in the Series/Index.
+
         Examples
         --------
         >>> import pyarrow as pa
@@ -128,6 +134,10 @@ def __getitem__(self, key: int | slice) -> Series:
         pandas.Series
             The list at requested index.
 
+        See Also
+        --------
+        ListAccessor.flatten : Flatten list values.
+
         Examples
         --------
         >>> import pyarrow as pa
@@ -187,6 +197,10 @@ def flatten(self) -> Series:
         pandas.Series
             The data from all lists in the series flattened.
 
+        See Also
+        --------
+        ListAccessor.__getitem__ : Index or slice values in the Series.
+
         Examples
         --------
         >>> import pyarrow as pa

pandas/core/arrays/sparse/array.py

@@ -671,6 +671,11 @@ def density(self) -> float:
         """
         The percent of non- ``fill_value`` points, as decimal.
 
+        See Also
+        --------
+        DataFrame.sparse.from_spmatrix : Create a new DataFrame from a
+            scipy sparse matrix.
+
         Examples
         --------
         >>> from pandas.arrays import SparseArray

pandas/core/generic.py

@@ -11815,6 +11815,8 @@ def last_valid_index(self) -> Hashable:
 Returns
 -------
 {name1} or scalar\
+
+    Value containing the calculation referenced in the description.\
 {see_also}\
 {examples}
 """

pandas/core/ops/docstrings.py

@@ -376,7 +376,7 @@ def make_flex_doc(op_name: str, typ: str) -> str:
     "ne": {
         "op": "!=",
         "desc": "Not equal to",
-        "reverse": None,
+        "reverse": "eq",
         "series_examples": _ne_example_SERIES,
         "series_returns": _returns_series,
     },
@@ -397,14 +397,14 @@ def make_flex_doc(op_name: str, typ: str) -> str:
     "gt": {
         "op": ">",
         "desc": "Greater than",
-        "reverse": None,
+        "reverse": "lt",
         "series_examples": _gt_example_SERIES,
         "series_returns": _returns_series,
     },
     "ge": {
         "op": ">=",
         "desc": "Greater than or equal to",
-        "reverse": None,
+        "reverse": "le",
         "series_examples": _ge_example_SERIES,
         "series_returns": _returns_series,
     },

pandas/core/series.py

@@ -4093,7 +4093,13 @@ def reorder_levels(self, order: Sequence[Level]) -> Series:
 
         Returns
         -------
-        type of caller (new object)
+        Series
+            Type of caller with index as MultiIndex (new object).
+
+        See Also
+        --------
+        DataFrame.reorder_levels : Rearrange index or column levels using
+            input ``order``.
 
         Examples
         --------
@@ -5048,6 +5054,11 @@ def pop(self, item: Hashable) -> Any:
         scalar
             Value that is popped from series.
 
+        See Also
+        --------
+        Series.drop: Drop specified values from Series.
+        Series.drop_duplicates: Return Series with duplicate values removed.
+
         Examples
         --------
         >>> ser = pd.Series([1, 2, 3])