DOC: Add docstring validations for "See Also" section (#23143)

Author: getschomp

scripts/tests/test_validate_docstrings.py

@@ -334,6 +334,33 @@ 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):
@@ -608,6 +635,11 @@ def test_bad_generic_functions(self, func):
         assert errors
 
     @pytest.mark.parametrize("klass,func,msgs", [
+        # See Also tests
+        ('BadSeeAlso', 'desc_no_period',
+         ('Missing period at end of description for See Also "Series.iloc"',)),
+        ('BadSeeAlso', 'desc_first_letter_lowercase',
+         ('should be capitalized for See Also "Series.tail"',)),
         # Summary tests
         ('BadSummaries', 'wrong_line',
          ('should start in the line immediately after the opening quotes',)),

scripts/validate_docstrings.py

@@ -505,7 +505,14 @@ def validate_one(func_name):
         wrns.append('See Also section not found')
     else:
         for rel_name, rel_desc in doc.see_also.items():
-            if not rel_desc:
+            if rel_desc:
+                if not rel_desc.endswith('.'):
+                    errs.append('Missing period at end of description for '
+                                'See Also "{}" reference'.format(rel_name))
+                if not rel_desc[0].isupper():
+                    errs.append('Description should be capitalized for '
+                                'See Also "{}" reference'.format(rel_name))
+            else:
                 errs.append('Missing description for '
                             'See Also "{}" reference'.format(rel_name))