From 76096d3782b9e1b0dff17d2dae08378cd1efd81f Mon Sep 17 00:00:00 2001
From: dilex <dilex.banana@gmail.com>
Date: Tue, 24 Mar 2020 12:22:22 +0200
Subject: [PATCH 1/3] DOC: Partial fix SA04 errors in docstrings #28792

---
 pandas/core/ops/docstrings.py | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/pandas/core/ops/docstrings.py b/pandas/core/ops/docstrings.py
index 203ea3946d1b2..e8164577074f1 100644
--- a/pandas/core/ops/docstrings.py
+++ b/pandas/core/ops/docstrings.py
@@ -33,9 +33,14 @@ def _make_flex_doc(op_name, typ):
             desc=op_desc["desc"],
             op_name=op_name,
             equiv=equiv,
-            reverse=op_desc["reverse"],
             series_returns=op_desc["series_returns"],
         )
+        if op_desc["reverse"]:
+            doc_see_also = _see_also_reverse_SERIES.format(
+                reverse=op_desc["reverse"],
+                see_also_desc=op_desc["see_also_desc"],
+            )
+            doc_no_examples = doc_no_examples + doc_see_also
         if op_desc["series_examples"]:
             doc = doc_no_examples + op_desc["series_examples"]
         else:
@@ -352,6 +357,10 @@ def _make_flex_doc(op_name, typ):
     if reverse_op is not None:
         _op_descriptions[reverse_op] = _op_descriptions[key].copy()
         _op_descriptions[reverse_op]["reverse"] = key
+        _op_descriptions[key]["see_also_desc"] = \
+            f"Reversed {_op_descriptions[key]['desc']}"
+        _op_descriptions[reverse_op]["see_also_desc"] = \
+            f"Usual {_op_descriptions[key]['desc']}"
 
 _flex_doc_SERIES = """
 Return {desc} of series and other, element-wise (binary operator `{op_name}`).
@@ -374,10 +383,12 @@ def _make_flex_doc(op_name, typ):
 Returns
 -------
 {series_returns}
+"""
 
+_see_also_reverse_SERIES = """
 See Also
 --------
-Series.{reverse}
+Series.{reverse} : {see_also_desc}.
 """
 
 _arith_doc_FRAME = """

From 620382e61a980b6b26487ff375c0a8e76a14deab Mon Sep 17 00:00:00 2001
From: dilex <dilex.banana@gmail.com>
Date: Tue, 24 Mar 2020 12:57:55 +0200
Subject: [PATCH 2/3] black formatting

---
 pandas/core/ops/docstrings.py | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/pandas/core/ops/docstrings.py b/pandas/core/ops/docstrings.py
index e8164577074f1..ee070a48fc665 100644
--- a/pandas/core/ops/docstrings.py
+++ b/pandas/core/ops/docstrings.py
@@ -37,8 +37,7 @@ def _make_flex_doc(op_name, typ):
         )
         if op_desc["reverse"]:
             doc_see_also = _see_also_reverse_SERIES.format(
-                reverse=op_desc["reverse"],
-                see_also_desc=op_desc["see_also_desc"],
+                reverse=op_desc["reverse"], see_also_desc=op_desc["see_also_desc"],
             )
             doc_no_examples = doc_no_examples + doc_see_also
         if op_desc["series_examples"]:
@@ -357,10 +356,12 @@ def _make_flex_doc(op_name, typ):
     if reverse_op is not None:
         _op_descriptions[reverse_op] = _op_descriptions[key].copy()
         _op_descriptions[reverse_op]["reverse"] = key
-        _op_descriptions[key]["see_also_desc"] = \
-            f"Reversed {_op_descriptions[key]['desc']}"
-        _op_descriptions[reverse_op]["see_also_desc"] = \
-            f"Usual {_op_descriptions[key]['desc']}"
+        _op_descriptions[key][
+            "see_also_desc"
+        ] = f"Reversed {_op_descriptions[key]['desc']}"
+        _op_descriptions[reverse_op][
+            "see_also_desc"
+        ] = f"Usual {_op_descriptions[key]['desc']}"
 
 _flex_doc_SERIES = """
 Return {desc} of series and other, element-wise (binary operator `{op_name}`).

From 091ea9e7edeea42f77c2df158cc30db68aa8b82d Mon Sep 17 00:00:00 2001
From: drollolo <reg007@droll.mail.ua>
Date: Thu, 2 Apr 2020 16:32:34 +0300
Subject: [PATCH 3/3] Change template to fix SA errors

---
 pandas/core/ops/docstrings.py | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/pandas/core/ops/docstrings.py b/pandas/core/ops/docstrings.py
index e84537bfe8cb0..449a477646c02 100644
--- a/pandas/core/ops/docstrings.py
+++ b/pandas/core/ops/docstrings.py
@@ -29,17 +29,16 @@ def _make_flex_doc(op_name, typ):
 
     if typ == "series":
         base_doc = _flex_doc_SERIES
+        if op_desc["reverse"]:
+            base_doc += _see_also_reverse_SERIES.format(
+                reverse=op_desc["reverse"], see_also_desc=op_desc["see_also_desc"],
+            )
         doc_no_examples = base_doc.format(
             desc=op_desc["desc"],
             op_name=op_name,
             equiv=equiv,
             series_returns=op_desc["series_returns"],
         )
-        if op_desc["reverse"]:
-            doc_see_also = _see_also_reverse_SERIES.format(
-                reverse=op_desc["reverse"], see_also_desc=op_desc["see_also_desc"],
-            )
-            doc_no_examples = doc_no_examples + doc_see_also
         if op_desc["series_examples"]:
             doc = doc_no_examples + op_desc["series_examples"]
         else:
@@ -379,6 +378,10 @@ def _make_flex_doc(op_name, typ):
     },
 }
 
+_py_num_ref = """see
+    `Python documentation
+    <https://docs.python.org/3/reference/datamodel.html#emulating-numeric-types>`_
+    for more details"""
 _op_names = list(_op_descriptions.keys())
 for key in _op_names:
     reverse_op = _op_descriptions[key]["reverse"]
@@ -387,10 +390,10 @@ def _make_flex_doc(op_name, typ):
         _op_descriptions[reverse_op]["reverse"] = key
         _op_descriptions[key][
             "see_also_desc"
-        ] = f"Reversed {_op_descriptions[key]['desc']}"
+        ] = f"Reverse of the {_op_descriptions[key]['desc']} operator, {_py_num_ref}"
         _op_descriptions[reverse_op][
             "see_also_desc"
-        ] = f"Usual {_op_descriptions[key]['desc']}"
+        ] = f"Element-wise {_op_descriptions[key]['desc']}, {_py_num_ref}"
 
 _flex_doc_SERIES = """
 Return {desc} of series and other, element-wise (binary operator `{op_name}`).