Repository: pandas-dev/pandas

Issue:
DOC: Validate that items in See Also section do not start by pandas.
`scripts/validate_docstrings.py` validates that the content of a docstring follows our standards. There are still some of those standards that the script does not validate, and this gives the users the wrong impression that the docstring is all right, when it's not really the case. All the missing validations are listed in #20298.

One of the standards is that the items in the `See Also` section should not start by `pandas.` as this is already configured in sphinx to be the default. So, instead of `pandas.DataFrame.head : Return the first n rows` we prefer `DataFrame.head : Return the first n rows`, as `pandas` is the default package,

For this issue is required:
- Change `scripts/validate_docstings.py` to give an error if the items have the prefix `pandas.`.
- Add tests in `scripts/tests/test_validate_docstrings.py`
- Run the script for all docstrings (i.e. ./scripts/validate_docstings.py) and check in the resulting report how many of the docstrings in pandas have these imports. Add as a comment in this issue the list, unless they are a reduced number, in which case they can be directly fixed in the same PR.


Discussion:
@datapythonista  I found 425 lines which starts with prefix `pandas.`. I will submit my PR now but please let me know if you want me to fix with this PR. 

Resolving patch:
diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py
--- 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 "{}", '


Test patch:
diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py
--- 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