DOC: Docstring script to not require ending period for bullet points

scripts/tests/test_validate_docstrings.py

@@ -252,6 +252,62 @@ def say_hello():
         else:
             return None
 
+    def parameters_with_bullet_points(self, method='min'):
+        """
+        Allow bullet points to end without a period.
+
+        Parameters
+        ----------
+        method : {'min', 'max'}, default 'min'
+            Parameter introduction:
+
+            * 'min': the description for min
+            * 'max': the description for max
+        """
+        pass
+
+    def parameters_with_bullet_points1(self, method='min'):
+        """
+        Allow long description in bullet points to end without a period.
+
+        Parameters
+        ----------
+        method : {'min', 'max'}, default 'min'
+            Parameter introduction:
+
+            * 'min': the description for min
+            * 'max': the description for max that can also be very long and
+              requires an extra row
+        """
+        pass
+
+    def parameters_bullet_points_and_directives(self, axis='index',
+                                                method='min'):
+        """
+        Test bullets points and directories.
+
+        Parameters
+        ----------
+        axis : {'index', 'columns'}, default 'index'
+            Parameter introduction and one directive:
+
+            * 'index': the description for index
+            * 'columns': the description for columns
+
+            .. versionchanged:: 0.1.2
+
+        method : {'min', 'max'}, default 'min'
+            Parameter introduction and two directives:
+
+            * 'min': the description for min
+            * 'max': the description for max
+
+            .. versionadded:: 0.1.2
+            .. deprecated:: 0.00.0
+                A description
+        """
+        pass
+
 
 class BadGenericDocStrings(object):
     """Everything here has a bad docstring
@@ -806,7 +862,9 @@ def test_good_class(self, capsys):
 
     @pytest.mark.parametrize("func", [
         'plot', 'sample', 'random_letters', 'sample_values', 'head', 'head1',
-        'contains', 'mode', 'good_imports', 'no_returns', 'empty_returns'])
+        'contains', 'mode', 'good_imports', 'no_returns', 'empty_returns',
+        'parameters_with_bullet_points', 'parameters_with_bullet_points1',
+        'parameters_bullet_points_and_directives'])
     def test_good_functions(self, capsys, func):
         errors = validate_one(self._import_path(
             klass='GoodDocStrings', func=func))['errors']

scripts/validate_docstrings.py

@@ -471,6 +471,46 @@ def parameter_desc(self, param):
                 desc = desc[:desc.index(full_directive)]
         return desc
 
+    def parameter_desc_list(self, param):
+        """Return a parameter description as a list.
+
+        Each line of the parameter docstring is a string in the list.
+        """
+        i = list(self.doc_parameters).index(param)
+        desc_list = [line
+                     # The 'Parameters' value of NumpyDocString._parsed_data is
+                     # a list of tuples. Each tuple represents a parameter
+                     # docstring parameter and has the description of
+                     # the parameter as last element.
+                     for line in self.doc._parsed_data['Parameters'][i][-1]
+                     if line]
+        # Find and strip out any sphinx directives
+        directives_pattern = re.compile('.. ({})'.format('|'.join(DIRECTIVES)))
+        for desc_item in desc_list:
+            if re.match(directives_pattern, desc_item):
+                # Only retain any description before the directive
+                desc_list = desc_list[:desc_list.index(desc_item)]
+                break
+        return desc_list
+
+    def has_proper_punctuation(self, param):
+        """Return True if a parameter description is terminated correctly.
+
+        A parameter description should always be terminated with a period, a
+        part from when it ends with a bullet point.
+        """
+        if self.parameter_desc(param)[-1] == '.':
+            return True
+        else:
+            # Return True if a parameter description ends
+            # with a bullet point
+            for desc_line in self.parameter_desc_list(param)[::-1]:
+                if desc_line[0] in ['*', '-', '+', '•', '‣', '⁃']:
+                    return True
+                elif desc_line[0:2] != '  ':
+                    return False
+            return False
+
     @property
     def see_also(self):
         return collections.OrderedDict((name, ''.join(desc))
@@ -724,7 +764,7 @@ def get_validation_data(doc):
         else:
             if not doc.parameter_desc(param)[0].isupper():
                 errs.append(error('PR08', param_name=param))
-            if doc.parameter_desc(param)[-1] != '.':
+            if not doc.has_proper_punctuation(param):
                 errs.append(error('PR09', param_name=param))
 
     if doc.is_function_or_method: