From 9bb2fa411860329e5cf9a61f05aac12635a38b96 Mon Sep 17 00:00:00 2001
From: Edoardo Abati <abati.edoardo@gmail.com>
Date: Tue, 19 Mar 2019 18:52:11 +0000
Subject: [PATCH 01/20] Check if parameter description ends with bullet point
 before raising PR09 error

---
 scripts/validate_docstrings.py | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py
index 1c45c79ba7fba..c7dbdbc95ada4 100755
--- a/scripts/validate_docstrings.py
+++ b/scripts/validate_docstrings.py
@@ -471,6 +471,18 @@ def parameter_desc(self, param):
                 desc = desc[:desc.index(full_directive)]
         return desc
 
+    def parameter_desc_list(self, param):
+        i = list(self.doc_parameters).index(param)
+        desc_list = self.doc._parsed_data['Parameters'][i][-1]
+        # Find and strip out any sphinx directives
+        for directive in DIRECTIVES:
+            full_directive = '.. {}'.format(directive)
+            for desc_item in desc_list:
+                if full_directive in desc_item:
+                    # Only retain any description before the directive
+                    desc_list = desc_list[:desc_list.index(desc_item)]
+        return desc_list
+
     @property
     def see_also(self):
         return collections.OrderedDict((name, ''.join(desc))
@@ -725,7 +737,21 @@ def get_validation_data(doc):
             if not doc.parameter_desc(param)[0].isupper():
                 errs.append(error('PR08', param_name=param))
             if doc.parameter_desc(param)[-1] != '.':
-                errs.append(error('PR09', param_name=param))
+
+                def end_with_bullet(param_desc_list):
+                    # Return True if a parameter description ends
+                    # with a bullet point
+                    desc_line = param_desc_list[-1]
+                    if desc_line and desc_line[0] in ['*', '-', '+']:
+                        return True
+                    elif desc_line and desc_line[0:2] == '  ':
+                        return end_with_bullet(param_desc_list[:-1])
+                    else:
+                        return False
+
+                desc_list = doc.parameter_desc_list(param)
+                if desc_list[-1][-1] != '.' and not end_with_bullet(desc_list):
+                    errs.append(error('PR09', param_name=param))
 
     if doc.is_function_or_method:
         if not doc.returns:

From 5fdfcc4078d939eed89be9d29f34bc9577c8b619 Mon Sep 17 00:00:00 2001
From: Edoardo Abati <abati.edoardo@gmail.com>
Date: Sun, 24 Mar 2019 19:09:13 +0000
Subject: [PATCH 02/20] fixed Docstring.parameter_desc_list for empty line and
 multiple directives

---
 scripts/validate_docstrings.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py
index c7dbdbc95ada4..3ed3af95fc61b 100755
--- a/scripts/validate_docstrings.py
+++ b/scripts/validate_docstrings.py
@@ -473,7 +473,8 @@ def parameter_desc(self, param):
 
     def parameter_desc_list(self, param):
         i = list(self.doc_parameters).index(param)
-        desc_list = self.doc._parsed_data['Parameters'][i][-1]
+        desc_list = [line for line in self.doc._parsed_data['Parameters'][i][-1]
+                     if line]
         # Find and strip out any sphinx directives
         for directive in DIRECTIVES:
             full_directive = '.. {}'.format(directive)
@@ -481,6 +482,7 @@ def parameter_desc_list(self, param):
                 if full_directive in desc_item:
                     # Only retain any description before the directive
                     desc_list = desc_list[:desc_list.index(desc_item)]
+                    break
         return desc_list
 
     @property

From 8b4a99ef3f0d0ad6a18865e5f2009ccbe7813549 Mon Sep 17 00:00:00 2001
From: Edoardo Abati <abati.edoardo@gmail.com>
Date: Sun, 24 Mar 2019 19:21:54 +0000
Subject: [PATCH 03/20] fixed PEP8 issue

---
 scripts/validate_docstrings.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py
index 3ed3af95fc61b..04c2e18ee0c95 100755
--- a/scripts/validate_docstrings.py
+++ b/scripts/validate_docstrings.py
@@ -473,7 +473,8 @@ def parameter_desc(self, param):
 
     def parameter_desc_list(self, param):
         i = list(self.doc_parameters).index(param)
-        desc_list = [line for line in self.doc._parsed_data['Parameters'][i][-1]
+        desc_list = [line
+                     for line in self.doc._parsed_data['Parameters'][i][-1]
                      if line]
         # Find and strip out any sphinx directives
         for directive in DIRECTIVES:

From 2b73e89fd458353a3f006fe2e32eb1569238efa3 Mon Sep 17 00:00:00 2001
From: Edoardo Abati <abati.edoardo@gmail.com>
Date: Tue, 26 Mar 2019 13:07:09 +0000
Subject: [PATCH 04/20] added test for parameters with bullet points

---
 scripts/tests/test_validate_docstrings.py | 32 ++++++++++++++++++++++-
 1 file changed, 31 insertions(+), 1 deletion(-)

diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py
index 120f8d79819ff..186a4036a6de9 100644
--- a/scripts/tests/test_validate_docstrings.py
+++ b/scripts/tests/test_validate_docstrings.py
@@ -252,6 +252,35 @@ 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
+
 
 class BadGenericDocStrings(object):
     """Everything here has a bad docstring
@@ -806,7 +835,8 @@ 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'])
     def test_good_functions(self, capsys, func):
         errors = validate_one(self._import_path(
             klass='GoodDocStrings', func=func))['errors']

From 587cb1281f6798f5c6951f439c7b5b45db860ed4 Mon Sep 17 00:00:00 2001
From: Edoardo Abati <abati.edoardo@gmail.com>
Date: Tue, 26 Mar 2019 23:46:56 +0000
Subject: [PATCH 05/20] created method that check if parameter ends correctly

---
 scripts/validate_docstrings.py | 33 +++++++++++++++++----------------
 1 file changed, 17 insertions(+), 16 deletions(-)

diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py
index 04c2e18ee0c95..bb140eca782d3 100755
--- a/scripts/validate_docstrings.py
+++ b/scripts/validate_docstrings.py
@@ -486,6 +486,21 @@ def parameter_desc_list(self, param):
                     break
         return desc_list
 
+    def parameter_correct_end(self, param):
+        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
+                else:
+                    pass
+            return False
+
     @property
     def see_also(self):
         return collections.OrderedDict((name, ''.join(desc))
@@ -739,22 +754,8 @@ 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] != '.':
-
-                def end_with_bullet(param_desc_list):
-                    # Return True if a parameter description ends
-                    # with a bullet point
-                    desc_line = param_desc_list[-1]
-                    if desc_line and desc_line[0] in ['*', '-', '+']:
-                        return True
-                    elif desc_line and desc_line[0:2] == '  ':
-                        return end_with_bullet(param_desc_list[:-1])
-                    else:
-                        return False
-
-                desc_list = doc.parameter_desc_list(param)
-                if desc_list[-1][-1] != '.' and not end_with_bullet(desc_list):
-                    errs.append(error('PR09', param_name=param))
+            if not doc.parameter_correct_end(param):
+                errs.append(error('PR09', param_name=param))
 
     if doc.is_function_or_method:
         if not doc.returns:

From c920656d9cef3b224c02105566a75849fff1415c Mon Sep 17 00:00:00 2001
From: Edoardo Abati <abati.edoardo@gmail.com>
Date: Thu, 28 Mar 2019 19:09:34 +0000
Subject: [PATCH 06/20] added extra bullet point markers

---
 scripts/validate_docstrings.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py
index bb140eca782d3..d8ddc97f65dee 100755
--- a/scripts/validate_docstrings.py
+++ b/scripts/validate_docstrings.py
@@ -493,7 +493,7 @@ def parameter_correct_end(self, param):
             # 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 ['*', '-', '+']:
+                if desc_line[0] in ['*', '-', '+', '•', '‣', '⁃']:
                     return True
                 elif desc_line[0:2] != '  ':
                     return False

From 060a499b41f38c907eb5367f99475bee260f730f Mon Sep 17 00:00:00 2001
From: Edoardo Abati <abati.edoardo@gmail.com>
Date: Mon, 1 Apr 2019 00:11:28 +0100
Subject: [PATCH 07/20] added docstrings to new methods

---
 scripts/validate_docstrings.py | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py
index d8ddc97f65dee..e88da448606e5 100755
--- a/scripts/validate_docstrings.py
+++ b/scripts/validate_docstrings.py
@@ -472,6 +472,10 @@ def parameter_desc(self, param):
         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
                      for line in self.doc._parsed_data['Parameters'][i][-1]
@@ -487,6 +491,11 @@ def parameter_desc_list(self, param):
         return desc_list
 
     def parameter_correct_end(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:

From 7c5375e03e9d013a7b7606536ce5956a95bb88b7 Mon Sep 17 00:00:00 2001
From: Edoardo Abati <abati.edoardo@gmail.com>
Date: Wed, 3 Apr 2019 18:11:50 +0100
Subject: [PATCH 08/20] added closing quote test

---
 scripts/tests/test_validate_docstrings.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py
index 186a4036a6de9..2974e4f5e5dec 100644
--- a/scripts/tests/test_validate_docstrings.py
+++ b/scripts/tests/test_validate_docstrings.py
@@ -258,7 +258,7 @@ def parameters_with_bullet_points(self, method='min'):
 
         Parameters
         ----------
-        method : {'min', 'max'}, default 'min
+        method : {'min', 'max'}, default 'min'
             Parameter introduction:
 
             * 'min': the description for min
@@ -272,7 +272,7 @@ def parameters_with_bullet_points1(self, method='min'):
 
         Parameters
         ----------
-        method : {'min', 'max'}, default 'min
+        method : {'min', 'max'}, default 'min'
             Parameter introduction:
 
             * 'min': the description for min

From 6b0267aca9c320688de8a8a858d20c6127639cb8 Mon Sep 17 00:00:00 2001
From: Edoardo Abati <abati.edoardo@gmail.com>
Date: Wed, 3 Apr 2019 18:17:48 +0100
Subject: [PATCH 09/20] added test for parameter with bullet points and
 directories

---
 scripts/tests/test_validate_docstrings.py | 30 ++++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py
index 2974e4f5e5dec..0d986894cc93f 100644
--- a/scripts/tests/test_validate_docstrings.py
+++ b/scripts/tests/test_validate_docstrings.py
@@ -281,6 +281,33 @@ def parameters_with_bullet_points1(self, method='min'):
         """
         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
@@ -836,7 +863,8 @@ 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',
-        'parameters_with_bullet_points', 'parameters_with_bullet_points1'])
+        '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']

From b387d0e496cd4d6ba3c2bdc4bd4df7ad21a7e810 Mon Sep 17 00:00:00 2001
From: Edoardo Abati <abati.edoardo@gmail.com>
Date: Sun, 28 Apr 2019 16:47:27 +0100
Subject: [PATCH 10/20] removed unnecessary else

---
 scripts/validate_docstrings.py | 2 --
 1 file changed, 2 deletions(-)

diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py
index e88da448606e5..b6aaa2c4ee854 100755
--- a/scripts/validate_docstrings.py
+++ b/scripts/validate_docstrings.py
@@ -506,8 +506,6 @@ def parameter_correct_end(self, param):
                     return True
                 elif desc_line[0:2] != '  ':
                     return False
-                else:
-                    pass
             return False
 
     @property

From aa240de928f194fa657a537032d2dcf80185d7b3 Mon Sep 17 00:00:00 2001
From: Edoardo Abati <abati.edoardo@gmail.com>
Date: Sun, 28 Apr 2019 16:49:27 +0100
Subject: [PATCH 11/20] renamed parameter to has_proper_punctuation

---
 scripts/validate_docstrings.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py
index b6aaa2c4ee854..c7614a09552d8 100755
--- a/scripts/validate_docstrings.py
+++ b/scripts/validate_docstrings.py
@@ -490,7 +490,7 @@ def parameter_desc_list(self, param):
                     break
         return desc_list
 
-    def parameter_correct_end(self, param):
+    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
@@ -761,7 +761,7 @@ def get_validation_data(doc):
         else:
             if not doc.parameter_desc(param)[0].isupper():
                 errs.append(error('PR08', param_name=param))
-            if not doc.parameter_correct_end(param):
+            if not doc.has_proper_punctuation(param):
                 errs.append(error('PR09', param_name=param))
 
     if doc.is_function_or_method:

From 146fae154fb307c0e374bf46c67c46e08641fbf2 Mon Sep 17 00:00:00 2001
From: Edoardo Abati <abati.edoardo@gmail.com>
Date: Wed, 26 Jun 2019 20:02:38 +0100
Subject: [PATCH 12/20] Added comment to clarify _parsed_data behaviour

---
 scripts/validate_docstrings.py | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py
index c7614a09552d8..c9a9e334cf81c 100755
--- a/scripts/validate_docstrings.py
+++ b/scripts/validate_docstrings.py
@@ -478,6 +478,10 @@ def parameter_desc_list(self, param):
         """
         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 have 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

From 85ac4f716209f10affd3bf48fcc235a0407a051b Mon Sep 17 00:00:00 2001
From: Edoardo Abati <abati.edoardo@gmail.com>
Date: Wed, 26 Jun 2019 20:03:09 +0100
Subject: [PATCH 13/20] Replaced for loop with regex match

---
 scripts/validate_docstrings.py | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py
index c9a9e334cf81c..32e58ddbfcb7a 100755
--- a/scripts/validate_docstrings.py
+++ b/scripts/validate_docstrings.py
@@ -485,13 +485,12 @@ def parameter_desc_list(self, param):
                      for line in self.doc._parsed_data['Parameters'][i][-1]
                      if line]
         # Find and strip out any sphinx directives
-        for directive in DIRECTIVES:
-            full_directive = '.. {}'.format(directive)
-            for desc_item in desc_list:
-                if full_directive in desc_item:
-                    # Only retain any description before the directive
-                    desc_list = desc_list[:desc_list.index(desc_item)]
-                    break
+        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):

From 5f3d14609f23cbd382b78c47da16c85a74d9dc57 Mon Sep 17 00:00:00 2001
From: Edoardo Abati <abati.edoardo@gmail.com>
Date: Wed, 26 Jun 2019 20:07:16 +0100
Subject: [PATCH 14/20] Fixed mistake in comment

---
 scripts/validate_docstrings.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py
index 32e58ddbfcb7a..0e27818fba9bc 100755
--- a/scripts/validate_docstrings.py
+++ b/scripts/validate_docstrings.py
@@ -480,7 +480,7 @@ def parameter_desc_list(self, param):
         desc_list = [line
                      # The 'Parameters' value of NumpyDocString._parsed_data is
                      # a list of tuples. Each tuple represents a parameter
-                     # docstring parameter and have the description of
+                     # docstring parameter and has the description of
                      # the parameter as last element.
                      for line in self.doc._parsed_data['Parameters'][i][-1]
                      if line]

From 43ae6ea59f40c772d22ef44565c5f08fe895c06f Mon Sep 17 00:00:00 2001
From: Edoardo Abati <abati.edoardo@gmail.com>
Date: Thu, 8 Aug 2019 22:55:38 +0100
Subject: [PATCH 15/20] use namedtuples to identify parameter in
 parameter_desc_list

---
 scripts/validate_docstrings.py | 14 ++++++--------
 1 file changed, 6 insertions(+), 8 deletions(-)

diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py
index b39c0dd1a4779..5f55ecfd6a22b 100755
--- a/scripts/validate_docstrings.py
+++ b/scripts/validate_docstrings.py
@@ -496,14 +496,12 @@ def parameter_desc_list(self, param):
 
         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]
+        # The 'Parameters' value of NumpyDocString._parsed_data is a list of
+        # NamedTuples.
+        parsed_param = [
+            p for p in self.doc._parsed_data["Parameters"] if p.name == param
+        ][0]
+        desc_list = [line for line in parsed_param.desc if line]
         # Find and strip out any sphinx directives
         directives_pattern = re.compile('.. ({})'.format('|'.join(DIRECTIVES)))
         for desc_item in desc_list:

From 1fec41db37d3ded88ed643c70c81ecd0dec92433 Mon Sep 17 00:00:00 2001
From: Edoardo Abati <abati.edoardo@gmail.com>
Date: Sun, 11 Aug 2019 19:30:39 +0100
Subject: [PATCH 16/20] Format code using black

---
 scripts/tests/test_validate_docstrings.py | 11 +++++------
 scripts/validate_docstrings.py            | 10 +++++-----
 2 files changed, 10 insertions(+), 11 deletions(-)

diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py
index 9e26a0c1bc200..ec18c744df227 100644
--- a/scripts/tests/test_validate_docstrings.py
+++ b/scripts/tests/test_validate_docstrings.py
@@ -255,7 +255,7 @@ def say_hello():
         else:
             return None
 
-    def parameters_with_bullet_points(self, method='min'):
+    def parameters_with_bullet_points(self, method="min"):
         """
         Allow bullet points to end without a period.
 
@@ -269,7 +269,7 @@ def parameters_with_bullet_points(self, method='min'):
         """
         pass
 
-    def parameters_with_bullet_points1(self, method='min'):
+    def parameters_with_bullet_points1(self, method="min"):
         """
         Allow long description in bullet points to end without a period.
 
@@ -284,8 +284,8 @@ def parameters_with_bullet_points1(self, method='min'):
         """
         pass
 
-    def parameters_bullet_points_and_directives(self, axis='index',
-                                                method='min'):
+    def parameters_bullet_points_and_directives(self, axis="index",
+                                                method="min"):
         """
         Test bullets points and directories.
 
@@ -873,10 +873,9 @@ def test_good_class(self, capsys):
             "empty_returns",
             "parameters_with_bullet_points",
             "parameters_with_bullet_points1",
-            "parameters_bullet_points_and_directives"
+            "parameters_bullet_points_and_directives",
         ],
     )
-
     def test_good_functions(self, capsys, func):
         errors = validate_one(self._import_path(klass="GoodDocStrings", func=func))[
             "errors"
diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py
index 5f55ecfd6a22b..b5dfca929997b 100755
--- a/scripts/validate_docstrings.py
+++ b/scripts/validate_docstrings.py
@@ -503,11 +503,11 @@ def parameter_desc_list(self, param):
         ][0]
         desc_list = [line for line in parsed_param.desc if line]
         # Find and strip out any sphinx directives
-        directives_pattern = re.compile('.. ({})'.format('|'.join(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)]
+                desc_list = desc_list[: desc_list.index(desc_item)]
                 break
         return desc_list
 
@@ -517,15 +517,15 @@ def has_proper_punctuation(self, param):
         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] == '.':
+        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 ['*', '-', '+', '•', '‣', '⁃']:
+                if desc_line[0] in ["*", "-", "+", "•", "‣", "⁃"]:
                     return True
-                elif desc_line[0:2] != '  ':
+                elif desc_line[0:2] != "  ":
                     return False
             return False
 

From 9c56d3001fdaa99c989a1384ca09911c98f12b43 Mon Sep 17 00:00:00 2001
From: Edoardo Abati <abati.edoardo@gmail.com>
Date: Tue, 13 Aug 2019 18:00:49 +0100
Subject: [PATCH 17/20] Minor format change with black

---
 scripts/tests/test_validate_docstrings.py | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py
index d1aaaea9f3100..fe3fcb8a3732d 100644
--- a/scripts/tests/test_validate_docstrings.py
+++ b/scripts/tests/test_validate_docstrings.py
@@ -284,8 +284,7 @@ def parameters_with_bullet_points1(self, method="min"):
         """
         pass
 
-    def parameters_bullet_points_and_directives(self, axis="index",
-                                                method="min"):
+    def parameters_bullet_points_and_directives(self, axis="index", method="min"):
         """
         Test bullets points and directories.
 

From 331e518387c161e73889164a70e348130fb4cfe1 Mon Sep 17 00:00:00 2001
From: Edoardo Abati <abati.edoardo@gmail.com>
Date: Sun, 22 Sep 2019 20:05:53 +0100
Subject: [PATCH 18/20] Tidying up with regex

---
 scripts/validate_docstrings.py | 20 +++++++++-----------
 1 file changed, 9 insertions(+), 11 deletions(-)

diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py
index dbf49b1a17804..2f6100db5120a 100755
--- a/scripts/validate_docstrings.py
+++ b/scripts/validate_docstrings.py
@@ -502,14 +502,11 @@ def parameter_desc_list(self, param):
 
         Each line of the parameter docstring is a string in the list.
         """
-        # The 'Parameters' value of NumpyDocString._parsed_data is a list of
-        # NamedTuples.
-        parsed_param = [
-            p for p in self.doc._parsed_data["Parameters"] if p.name == param
-        ][0]
+        # Get the parameter description as list and remove any empty lines
+        parsed_param = [p for p in self.doc["Parameters"] if p.name == param][0]
         desc_list = [line for line in parsed_param.desc if line]
         # Find and strip out any sphinx directives
-        directives_pattern = re.compile(".. ({})".format("|".join(DIRECTIVES)))
+        directives_pattern = re.compile(rf"\.\. ({'|'.join(DIRECTIVES)})::")
         for desc_item in desc_list:
             if re.match(directives_pattern, desc_item):
                 # Only retain any description before the directive
@@ -526,12 +523,13 @@ def has_proper_punctuation(self, param):
         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 ["*", "-", "+", "•", "‣", "⁃"]:
+            # Check the parameter description list in reverse, stop returning True
+            # if a line start with a bullet point or returning False if a line does not
+            # start with two whitespaces
+            for desc_line in reversed(self.parameter_desc_list(param)):
+                if re.match(r"^(\*|-|\+|•|‣|⁃)\s", desc_line):
                     return True
-                elif desc_line[0:2] != "  ":
+                elif not re.match(r"^\s\s", desc_line):
                     return False
             return False
 

From fe5d7236a4ce1a4be36eec547261cf38c635c4fb Mon Sep 17 00:00:00 2001
From: Edoardo Abati <abati.edoardo@gmail.com>
Date: Sun, 22 Sep 2019 20:12:07 +0100
Subject: [PATCH 19/20] Simplified has_proper_punctuation with regex

---
 scripts/validate_docstrings.py | 32 +++++++-------------------------
 1 file changed, 7 insertions(+), 25 deletions(-)

diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py
index 2f6100db5120a..42cdf2f303995 100755
--- a/scripts/validate_docstrings.py
+++ b/scripts/validate_docstrings.py
@@ -60,6 +60,7 @@
 PRIVATE_CLASSES = ["NDFrame", "IndexOpsMixin"]
 DIRECTIVES = ["versionadded", "versionchanged", "deprecated"]
 DIRECTIVE_PATTERN = re.compile(rf"^\s*\.\. ({'|'.join(DIRECTIVES)})(?!::)", re.I | re.M)
+BULLET_LIST_PATTERN = re.compile(r"(?<=:)(\*|-|\+|•|‣|⁃)\s.*")
 ALLOWED_SECTIONS = [
     "Parameters",
     "Attributes",
@@ -497,23 +498,6 @@ 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.
-        """
-        # Get the parameter description as list and remove any empty lines
-        parsed_param = [p for p in self.doc["Parameters"] if p.name == param][0]
-        desc_list = [line for line in parsed_param.desc if line]
-        # Find and strip out any sphinx directives
-        directives_pattern = re.compile(rf"\.\. ({'|'.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.
 
@@ -523,14 +507,12 @@ def has_proper_punctuation(self, param):
         if self.parameter_desc(param)[-1] == ".":
             return True
         else:
-            # Check the parameter description list in reverse, stop returning True
-            # if a line start with a bullet point or returning False if a line does not
-            # start with two whitespaces
-            for desc_line in reversed(self.parameter_desc_list(param)):
-                if re.match(r"^(\*|-|\+|•|‣|⁃)\s", desc_line):
-                    return True
-                elif not re.match(r"^\s\s", desc_line):
-                    return False
+            # Check if the parameter description ends with a bullet list
+            bullet_list_match = re.search(
+                BULLET_LIST_PATTERN, self.parameter_desc(param)
+            )
+            if bullet_list_match:
+                return bullet_list_match.endpos == len(self.parameter_desc(param))
             return False
 
     @property

From f556faa6871c58dfa1b5baa3135b90cac492ad6f Mon Sep 17 00:00:00 2001
From: Edoardo Abati <abati.edoardo@gmail.com>
Date: Mon, 23 Sep 2019 22:15:01 +0100
Subject: [PATCH 20/20] remove unnecessary check

---
 scripts/validate_docstrings.py | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py
index 42cdf2f303995..9903917f6b882 100755
--- a/scripts/validate_docstrings.py
+++ b/scripts/validate_docstrings.py
@@ -508,11 +508,8 @@ def has_proper_punctuation(self, param):
             return True
         else:
             # Check if the parameter description ends with a bullet list
-            bullet_list_match = re.search(
-                BULLET_LIST_PATTERN, self.parameter_desc(param)
-            )
-            if bullet_list_match:
-                return bullet_list_match.endpos == len(self.parameter_desc(param))
+            if re.search(BULLET_LIST_PATTERN, self.parameter_desc(param)):
+                return True
             return False
 
     @property