For issue pandas-dev#23135 Validate the description of the See Also

Author: percevalve

scripts/tests/test_validate_docstrings.py

@@ -5,6 +5,7 @@
 import numpy as np
 
 import validate_docstrings
+
 validate_one = validate_docstrings.validate_one
 
 from pandas.util.testing import capture_stderr
@@ -18,7 +19,7 @@ class GoodDocStrings(object):
     script without any errors.
     """
 
-    def plot(self, kind, color='blue', **kwargs):
+    def plot(self, kind, color="blue", **kwargs):
         """
         Generate a plot.
 
@@ -218,6 +219,9 @@ def mode(self, axis, numeric_only):
         """
         pass
 
+    def SeeAlsoFormatting(self):
+        pass
+
 
 class BadGenericDocStrings(object):
     """Everything here has a bad docstring
@@ -335,7 +339,6 @@ def method(self, foo=None, bar=None):
 
 
 class BadSummaries(object):
-
     def wrong_line(self):
         """Exists on the wrong line"""
         pass
@@ -457,7 +460,6 @@ def blank_lines(self, kind):
 
 
 class BadReturns(object):
-
     def return_not_documented(self):
         """
         Lacks section for Returns
@@ -502,8 +504,31 @@ def no_punctuation(self):
         return "Hello world!"
 
 
-class TestValidator(object):
+class BadSeeAlso(object):
+    """
+    Everything here has a problem with its See Also section.
+    """
+
+    def no_period_see_also(self):
+        """
+        Provides type and description but no period.
+
+        See Also
+        -------
+        str : Lorem ipsum
+        """
+
+    def no_capital_first_see_also(self):
+        """
+        Provides type and description first letter is not capitalized.
+
+        See Also
+        -------
+        str : lorem ipsum.
+        """
 
+
+class TestValidator(object):
     def _import_path(self, klass=None, func=None):
         """
         Build the required import path for tests in this module.
@@ -532,86 +557,144 @@ def _import_path(self, klass=None, func=None):
 
     @capture_stderr
     def test_good_class(self):
-        errors = validate_one(self._import_path(
-            klass='GoodDocStrings'))['errors']
+        errors = validate_one(self._import_path(klass="GoodDocStrings"))["errors"]
         assert isinstance(errors, list)
         assert not errors
 
     @capture_stderr
-    @pytest.mark.parametrize("func", [
-        'plot', 'sample', 'random_letters', 'sample_values', 'head', 'head1',
-        'contains', 'mode'])
+    @pytest.mark.parametrize(
+        "func",
+        [
+            "plot",
+            "sample",
+            "random_letters",
+            "sample_values",
+            "head",
+            "head1",
+            "contains",
+            "mode",
+        ],
+    )
     def test_good_functions(self, func):
-        errors = validate_one(self._import_path(
-            klass='GoodDocStrings', func=func))['errors']
+        errors = validate_one(self._import_path(klass="GoodDocStrings", func=func))[
+            "errors"
+        ]
         assert isinstance(errors, list)
         assert not errors
 
     @capture_stderr
     def test_bad_class(self):
-        errors = validate_one(self._import_path(
-            klass='BadGenericDocStrings'))['errors']
+        errors = validate_one(self._import_path(klass="BadGenericDocStrings"))["errors"]
         assert isinstance(errors, list)
         assert errors
 
     @capture_stderr
-    @pytest.mark.parametrize("func", [
-        'func', 'astype', 'astype1', 'astype2', 'astype3', 'plot', 'method'])
+    @pytest.mark.parametrize(
+        "func", ["func", "astype", "astype1", "astype2", "astype3", "plot", "method"]
+    )
     def test_bad_generic_functions(self, func):
-        errors = validate_one(self._import_path(  # noqa:F821
-            klass='BadGenericDocStrings', func=func))['errors']
+        errors = validate_one(
+            self._import_path(klass="BadGenericDocStrings", func=func)  # noqa:F821
+        )["errors"]
         assert isinstance(errors, list)
         assert errors
 
-    @pytest.mark.parametrize("klass,func,msgs", [
-        # Summary tests
-        ('BadSummaries', 'wrong_line',
-         ('should start in the line immediately after the opening quotes',)),
-        ('BadSummaries', 'no_punctuation',
-         ('Summary does not end with a period',)),
-        ('BadSummaries', 'no_capitalization',
-         ('Summary does not start with a capital letter',)),
-        ('BadSummaries', 'no_capitalization',
-         ('Summary must start with infinitive verb',)),
-        ('BadSummaries', 'multi_line',
-         ('Summary should fit in a single line.',)),
-        ('BadSummaries', 'two_paragraph_multi_line',
-         ('Summary should fit in a single line.',)),
-        # Parameters tests
-        ('BadParameters', 'missing_params',
-         ('Parameters {**kwargs} not documented',)),
-        ('BadParameters', 'bad_colon_spacing',
-         ('Parameters {kind} not documented',
-          'Unknown parameters {kind: str}',
-          'Parameter "kind: str" has no type')),
-        ('BadParameters', 'no_description_period',
-         ('Parameter "kind" description should finish with "."',)),
-        ('BadParameters', 'no_description_period_with_directive',
-         ('Parameter "kind" description should finish with "."',)),
-        ('BadParameters', 'parameter_capitalization',
-         ('Parameter "kind" description should start with a capital letter',)),
-        pytest.param('BadParameters', 'blank_lines', ('No error yet?',),
-                     marks=pytest.mark.xfail),
-        # Returns tests
-        ('BadReturns', 'return_not_documented', ('No Returns section found',)),
-        ('BadReturns', 'yield_not_documented', ('No Yields section found',)),
-        pytest.param('BadReturns', 'no_type', ('foo',),
-                     marks=pytest.mark.xfail),
-        pytest.param('BadReturns', 'no_description', ('foo',),
-                     marks=pytest.mark.xfail),
-        pytest.param('BadReturns', 'no_punctuation', ('foo',),
-                     marks=pytest.mark.xfail)
-    ])
+    @pytest.mark.parametrize(
+        "klass,func,msgs",
+        [
+            # Summary tests
+            (
+                "BadSummaries",
+                "wrong_line",
+                ("should start in the line immediately after the opening quotes",),
+            ),
+            ("BadSummaries", "no_punctuation", ("Summary does not end with a period",)),
+            (
+                "BadSummaries",
+                "no_capitalization",
+                ("Summary does not start with a capital letter",),
+            ),
+            (
+                "BadSummaries",
+                "no_capitalization",
+                ("Summary must start with infinitive verb",),
+            ),
+            ("BadSummaries", "multi_line", ("Summary should fit in a single line.",)),
+            (
+                "BadSummaries",
+                "two_paragraph_multi_line",
+                ("Summary should fit in a single line.",),
+            ),
+            # Parameters tests
+            (
+                "BadParameters",
+                "missing_params",
+                ("Parameters {**kwargs} not documented",),
+            ),
+            (
+                "BadParameters",
+                "bad_colon_spacing",
+                (
+                    "Parameters {kind} not documented",
+                    "Unknown parameters {kind: str}",
+                    'Parameter "kind: str" has no type',
+                ),
+            ),
+            (
+                "BadParameters",
+                "no_description_period",
+                ('Parameter "kind" description should finish with "."',),
+            ),
+            (
+                "BadParameters",
+                "no_description_period_with_directive",
+                ('Parameter "kind" description should finish with "."',),
+            ),
+            (
+                "BadParameters",
+                "parameter_capitalization",
+                ('Parameter "kind" description should start with a capital letter',),
+            ),
+            pytest.param(
+                "BadParameters",
+                "blank_lines",
+                ("No error yet?",),
+                marks=pytest.mark.xfail,
+            ),
+            # Returns tests
+            ("BadReturns", "return_not_documented", ("No Returns section found",)),
+            ("BadReturns", "yield_not_documented", ("No Yields section found",)),
+            pytest.param("BadReturns", "no_type", ("foo",), marks=pytest.mark.xfail),
+            pytest.param(
+                "BadReturns", "no_description", ("foo",), marks=pytest.mark.xfail
+            ),
+            pytest.param(
+                "BadReturns", "no_punctuation", ("foo",), marks=pytest.mark.xfail
+            ),
+            # See Also tests
+            (
+                "BadSeeAlso",
+                "no_period_see_also",
+                ("No period at the end of the See Also.",),
+            ),
+            (
+                "BadSeeAlso",
+                "no_capital_first_see_also",
+                ("First letter of the See Also is not capitalized.",),
+            ),
+        ],
+    )
     def test_bad_examples(self, capsys, klass, func, msgs):
         result = validate_one(self._import_path(klass=klass, func=func))  # noqa:F821
         for msg in msgs:
-            assert msg in ' '.join(result['errors'])
+            assert msg in " ".join(result["errors"])
 
 
 class ApiItems(object):
     @property
     def api_doc(self):
-        return io.StringIO('''
+        return io.StringIO(
+            """
 .. currentmodule:: itertools
 
 Itertools
@@ -644,41 +727,50 @@ def api_doc(self):
 
     seed
     randint
-''')
-
-    @pytest.mark.parametrize('idx,name', [(0, 'itertools.cycle'),
-                                          (1, 'itertools.count'),
-                                          (2, 'itertools.chain'),
-                                          (3, 'random.seed'),
-                                          (4, 'random.randint')])
+"""
+        )
+
+    @pytest.mark.parametrize(
+        "idx,name",
+        [
+            (0, "itertools.cycle"),
+            (1, "itertools.count"),
+            (2, "itertools.chain"),
+            (3, "random.seed"),
+            (4, "random.randint"),
+        ],
+    )
     def test_item_name(self, idx, name):
         result = list(validate_docstrings.get_api_items(self.api_doc))
         assert result[idx][0] == name
 
-    @pytest.mark.parametrize('idx,func', [(0, 'cycle'),
-                                          (1, 'count'),
-                                          (2, 'chain'),
-                                          (3, 'seed'),
-                                          (4, 'randint')])
+    @pytest.mark.parametrize(
+        "idx,func",
+        [(0, "cycle"), (1, "count"), (2, "chain"), (3, "seed"), (4, "randint")],
+    )
     def test_item_function(self, idx, func):
         result = list(validate_docstrings.get_api_items(self.api_doc))
         assert callable(result[idx][1])
         assert result[idx][1].__name__ == func
 
-    @pytest.mark.parametrize('idx,section', [(0, 'Itertools'),
-                                             (1, 'Itertools'),
-                                             (2, 'Itertools'),
-                                             (3, 'Random'),
-                                             (4, 'Random')])
+    @pytest.mark.parametrize(
+        "idx,section",
+        [
+            (0, "Itertools"),
+            (1, "Itertools"),
+            (2, "Itertools"),
+            (3, "Random"),
+            (4, "Random"),
+        ],
+    )
     def test_item_section(self, idx, section):
         result = list(validate_docstrings.get_api_items(self.api_doc))
         assert result[idx][2] == section
 
-    @pytest.mark.parametrize('idx,subsection', [(0, 'Infinite'),
-                                                (1, 'Infinite'),
-                                                (2, 'Finite'),
-                                                (3, 'All'),
-                                                (4, 'All')])
+    @pytest.mark.parametrize(
+        "idx,subsection",
+        [(0, "Infinite"), (1, "Infinite"), (2, "Finite"), (3, "All"), (4, "All")],
+    )
     def test_item_subsection(self, idx, subsection):
         result = list(validate_docstrings.get_api_items(self.api_doc))
         assert result[idx][3] == subsection