From da9d85122a5b36b89fffa8f86ef768db20fc64c0 Mon Sep 17 00:00:00 2001
From: Thein Oo <thoo@users.noreply.github.com>
Date: Sat, 27 Oct 2018 14:20:15 -0400
Subject: [PATCH] DOC: Validate that See Also section items do not contain the
 pandas. prefix (#23145)

---
 scripts/tests/test_validate_docstrings.py | 71 ++++++++++++++---------
 scripts/validate_docstrings.py            |  5 +-
 2 files changed, 47 insertions(+), 29 deletions(-)

diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py
index 6bf832fb9dc6d..0e10265a7291d 100644
--- a/scripts/tests/test_validate_docstrings.py
+++ b/scripts/tests/test_validate_docstrings.py
@@ -334,33 +334,6 @@ def method(self, foo=None, bar=None):
         pass
 
 
-class BadSeeAlso(object):
-
-    def desc_no_period(self):
-        """
-        Return the first 5 elements of the Series.
-
-        See Also
-        --------
-        Series.tail : Return the last 5 elements of the Series.
-        Series.iloc : Return a slice of the elements in the Series,
-            which can also be used to return the first or last n
-        """
-        pass
-
-    def desc_first_letter_lowercase(self):
-        """
-        Return the first 5 elements of the Series.
-
-        See Also
-        --------
-        Series.tail : return the last 5 elements of the Series.
-        Series.iloc : Return a slice of the elements in the Series,
-            which can also be used to return the first or last n.
-        """
-        pass
-
-
 class BadSummaries(object):
 
     def wrong_line(self):
@@ -573,6 +546,44 @@ def no_punctuation(self):
         return "Hello world!"
 
 
+class BadSeeAlso(object):
+
+    def desc_no_period(self):
+        """
+        Return the first 5 elements of the Series.
+
+        See Also
+        --------
+        Series.tail : Return the last 5 elements of the Series.
+        Series.iloc : Return a slice of the elements in the Series,
+            which can also be used to return the first or last n
+        """
+        pass
+
+    def desc_first_letter_lowercase(self):
+        """
+        Return the first 5 elements of the Series.
+
+        See Also
+        --------
+        Series.tail : return the last 5 elements of the Series.
+        Series.iloc : Return a slice of the elements in the Series,
+            which can also be used to return the first or last n.
+        """
+        pass
+
+    def prefix_pandas(self):
+        """
+        Have `pandas` prefix in See Also section.
+
+        See Also
+        --------
+        pandas.Series.rename : Alter Series index labels or name.
+        DataFrame.head : The first `n` rows of the caller object.
+        """
+        pass
+
+
 class TestValidator(object):
 
     def _import_path(self, klass=None, func=None):
@@ -688,7 +699,11 @@ def test_bad_generic_functions(self, func):
         pytest.param('BadReturns', 'no_description', ('foo',),
                      marks=pytest.mark.xfail),
         pytest.param('BadReturns', 'no_punctuation', ('foo',),
-                     marks=pytest.mark.xfail)
+                     marks=pytest.mark.xfail),
+        # See Also tests
+        ('BadSeeAlso', 'prefix_pandas',
+         ('pandas.Series.rename in `See Also` section '
+          'does not need `pandas` prefix',))
     ])
     def test_bad_examples(self, capsys, klass, func, msgs):
         result = validate_one(self._import_path(klass=klass, func=func))  # noqa:F821
diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py
index 2fef3332de55c..29d485550be40 100755
--- a/scripts/validate_docstrings.py
+++ b/scripts/validate_docstrings.py
@@ -515,7 +515,10 @@ def validate_one(func_name):
             else:
                 errs.append('Missing description for '
                             'See Also "{}" reference'.format(rel_name))
-
+            if rel_name.startswith('pandas.'):
+                errs.append('{} in `See Also` section does not '
+                            'need `pandas` prefix, use {} instead.'
+                            .format(rel_name, rel_name[len('pandas.'):]))
     for line in doc.raw_doc.splitlines():
         if re.match("^ *\t", line):
             errs.append('Tabs found at the start of line "{}", '