Repository: pandas-dev/pandas

Issue:
DOC: Validate description of See Also section in docstrings
`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 descriptions in the `See Also` section should start by a capital letter and finish with a period.

For this issue is required:
- Change `scripts/validate_docstings.py` to give an error if the descriptions do not follow to mentioned standard.
- 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.


Discussion:

Resolving patch:
diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py
--- a/scripts/validate_docstrings.py
+++ b/scripts/validate_docstrings.py
@@ -496,7 +496,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))
 


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,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):
@@ -564,6 +591,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',)),