DOC: Add examples to Series operators (#24589) (#32704)

* DOC: add series examples (#24589)

adds documentation example to:
- `pandas.Series.eq`
- `pandas.Series.ne`
- `pandas.Series.gt`,
- `pandas.Series.ge`
- `pandas.series.le`
- `pandas.series.lt`

Author: sullivanbt

pandas/core/ops/docstrings.py

@@ -53,7 +53,7 @@ def _make_flex_doc(op_name, typ):
     return doc
 
 
-_add_example_SERIES = """
+_common_examples_algebra_SERIES = """
 Examples
 --------
 >>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd'])
@@ -69,33 +69,44 @@ def _make_flex_doc(op_name, typ):
 b    NaN
 d    1.0
 e    NaN
-dtype: float64
->>> a.add(b, fill_value=0)
-a    2.0
-b    1.0
-c    1.0
-d    1.0
-e    NaN
-dtype: float64
-"""
+dtype: float64"""
 
-_sub_example_SERIES = """
+_common_examples_comparison_SERIES = """
 Examples
 --------
->>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd'])
+>>> a = pd.Series([1, 1, 1, np.nan, 1], index=['a', 'b', 'c', 'd', 'e'])
 >>> a
 a    1.0
 b    1.0
 c    1.0
 d    NaN
+e    1.0
 dtype: float64
->>> b = pd.Series([1, np.nan, 1, np.nan], index=['a', 'b', 'd', 'e'])
+>>> b = pd.Series([0, 1, 2, np.nan, 1], index=['a', 'b', 'c', 'd', 'f'])
 >>> b
-a    1.0
-b    NaN
+a    0.0
+b    1.0
+c    2.0
+d    NaN
+f    1.0
+dtype: float64"""
+
+_add_example_SERIES = (
+    _common_examples_algebra_SERIES
+    + """
+>>> a.add(b, fill_value=0)
+a    2.0
+b    1.0
+c    1.0
 d    1.0
 e    NaN
 dtype: float64
+"""
+)
+
+_sub_example_SERIES = (
+    _common_examples_algebra_SERIES
+    + """
 >>> a.subtract(b, fill_value=0)
 a    0.0
 b    1.0
@@ -104,24 +115,11 @@ def _make_flex_doc(op_name, typ):
 e    NaN
 dtype: float64
 """
+)
 
-_mul_example_SERIES = """
-Examples
---------
->>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd'])
->>> a
-a    1.0
-b    1.0
-c    1.0
-d    NaN
-dtype: float64
->>> b = pd.Series([1, np.nan, 1, np.nan], index=['a', 'b', 'd', 'e'])
->>> b
-a    1.0
-b    NaN
-d    1.0
-e    NaN
-dtype: float64
+_mul_example_SERIES = (
+    _common_examples_algebra_SERIES
+    + """
 >>> a.multiply(b, fill_value=0)
 a    1.0
 b    0.0
@@ -130,24 +128,11 @@ def _make_flex_doc(op_name, typ):
 e    NaN
 dtype: float64
 """
+)
 
-_div_example_SERIES = """
-Examples
---------
->>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd'])
->>> a
-a    1.0
-b    1.0
-c    1.0
-d    NaN
-dtype: float64
->>> b = pd.Series([1, np.nan, 1, np.nan], index=['a', 'b', 'd', 'e'])
->>> b
-a    1.0
-b    NaN
-d    1.0
-e    NaN
-dtype: float64
+_div_example_SERIES = (
+    _common_examples_algebra_SERIES
+    + """
 >>> a.divide(b, fill_value=0)
 a    1.0
 b    inf
@@ -156,24 +141,11 @@ def _make_flex_doc(op_name, typ):
 e    NaN
 dtype: float64
 """
+)
 
-_floordiv_example_SERIES = """
-Examples
---------
->>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd'])
->>> a
-a    1.0
-b    1.0
-c    1.0
-d    NaN
-dtype: float64
->>> b = pd.Series([1, np.nan, 1, np.nan], index=['a', 'b', 'd', 'e'])
->>> b
-a    1.0
-b    NaN
-d    1.0
-e    NaN
-dtype: float64
+_floordiv_example_SERIES = (
+    _common_examples_algebra_SERIES
+    + """
 >>> a.floordiv(b, fill_value=0)
 a    1.0
 b    NaN
@@ -182,24 +154,11 @@ def _make_flex_doc(op_name, typ):
 e    NaN
 dtype: float64
 """
+)
 
-_mod_example_SERIES = """
-Examples
---------
->>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd'])
->>> a
-a    1.0
-b    1.0
-c    1.0
-d    NaN
-dtype: float64
->>> b = pd.Series([1, np.nan, 1, np.nan], index=['a', 'b', 'd', 'e'])
->>> b
-a    1.0
-b    NaN
-d    1.0
-e    NaN
-dtype: float64
+_mod_example_SERIES = (
+    _common_examples_algebra_SERIES
+    + """
 >>> a.mod(b, fill_value=0)
 a    0.0
 b    NaN
@@ -208,23 +167,10 @@ def _make_flex_doc(op_name, typ):
 e    NaN
 dtype: float64
 """
-_pow_example_SERIES = """
-Examples
---------
->>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd'])
->>> a
-a    1.0
-b    1.0
-c    1.0
-d    NaN
-dtype: float64
->>> b = pd.Series([1, np.nan, 1, np.nan], index=['a', 'b', 'd', 'e'])
->>> b
-a    1.0
-b    NaN
-d    1.0
-e    NaN
-dtype: float64
+)
+_pow_example_SERIES = (
+    _common_examples_algebra_SERIES
+    + """
 >>> a.pow(b, fill_value=0)
 a    1.0
 b    1.0
@@ -233,6 +179,89 @@ def _make_flex_doc(op_name, typ):
 e    NaN
 dtype: float64
 """
+)
+
+_ne_example_SERIES = (
+    _common_examples_algebra_SERIES
+    + """
+>>> a.ne(b, fill_value=0)
+a    False
+b     True
+c     True
+d     True
+e     True
+dtype: bool
+"""
+)
+
+_eq_example_SERIES = (
+    _common_examples_algebra_SERIES
+    + """
+>>> a.eq(b, fill_value=0)
+a     True
+b    False
+c    False
+d    False
+e    False
+dtype: bool
+"""
+)
+
+_lt_example_SERIES = (
+    _common_examples_comparison_SERIES
+    + """
+>>> a.lt(b, fill_value=0)
+a    False
+b    False
+c     True
+d    False
+e    False
+f     True
+dtype: bool
+"""
+)
+
+_le_example_SERIES = (
+    _common_examples_comparison_SERIES
+    + """
+>>> a.le(b, fill_value=0)
+a    False
+b     True
+c     True
+d    False
+e    False
+f     True
+dtype: bool
+"""
+)
+
+_gt_example_SERIES = (
+    _common_examples_comparison_SERIES
+    + """
+>>> a.gt(b, fill_value=0)
+a     True
+b    False
+c    False
+d    False
+e     True
+f    False
+dtype: bool
+"""
+)
+
+_ge_example_SERIES = (
+    _common_examples_comparison_SERIES
+    + """
+>>> a.ge(b, fill_value=0)
+a     True
+b     True
+c    False
+d    False
+e     True
+f    False
+dtype: bool
+"""
+)
 
 _returns_series = """Series\n    The result of the operation."""
 
@@ -306,42 +335,42 @@ def _make_flex_doc(op_name, typ):
         "op": "==",
         "desc": "Equal to",
         "reverse": None,
-        "series_examples": None,
+        "series_examples": _eq_example_SERIES,
         "series_returns": _returns_series,
     },
     "ne": {
         "op": "!=",
         "desc": "Not equal to",
         "reverse": None,
-        "series_examples": None,
+        "series_examples": _ne_example_SERIES,
         "series_returns": _returns_series,
     },
     "lt": {
         "op": "<",
         "desc": "Less than",
         "reverse": None,
-        "series_examples": None,
+        "series_examples": _lt_example_SERIES,
         "series_returns": _returns_series,
     },
     "le": {
         "op": "<=",
         "desc": "Less than or equal to",
         "reverse": None,
-        "series_examples": None,
+        "series_examples": _le_example_SERIES,
         "series_returns": _returns_series,
     },
     "gt": {
         "op": ">",
         "desc": "Greater than",
         "reverse": None,
-        "series_examples": None,
+        "series_examples": _gt_example_SERIES,
         "series_returns": _returns_series,
     },
     "ge": {
         "op": ">=",
         "desc": "Greater than or equal to",
         "reverse": None,
-        "series_examples": None,
+        "series_examples": _ge_example_SERIES,
         "series_returns": _returns_series,
     },
 }