Validate docstring directives

Fix pandas-dev#27629

Author: albertvillanova

scripts/validate_docstrings.py

@@ -93,6 +93,7 @@
     "GL07": "Sections are in the wrong order. Correct order is: " "{correct_sections}",
     "GL08": "The object does not have a docstring",
     "GL09": "Deprecation warning should precede extended summary",
+    "GL10": "reST directives {directives} must be followed by two colons",
     "SS01": "No summary found (a short summary in a single line should be "
     "present at the beginning of the docstring)",
     "SS02": "Summary does not start with a capital letter",
@@ -239,6 +240,10 @@ def get_api_items(api_doc_fd):
 
 
 class Docstring:
+    DIRECTIVES = ['deprecated', 'versionadded', 'versionchanged']
+    DIRECTIVE_WITHOUT_TWO_COLONS = re.compile(
+        rf"^\s*.. ({'|'.join(DIRECTIVES)})(?!::)", re.I | re.M)
+
     def __init__(self, name):
         self.name = name
         obj = self._load_obj(name)
@@ -478,6 +483,10 @@ def parameter_mismatches(self):
     def correct_parameters(self):
         return not bool(self.parameter_mismatches)
 
+    @property
+    def directives_without_two_colons(self):
+        return Docstring.DIRECTIVE_WITHOUT_TWO_COLONS.findall(self.raw_doc)
+
     def parameter_type(self, param):
         return self.doc_parameters[param][0]
 
@@ -697,6 +706,10 @@ def get_validation_data(doc):
     if doc.deprecated and not doc.extended_summary.startswith(".. deprecated:: "):
         errs.append(error("GL09"))
 
+    directives_without_two_colons = doc.directives_without_two_colons
+    if directives_without_two_colons:
+        errs.append(error("GL10", directives=directives_without_two_colons))
+
     if not doc.summary:
         errs.append(error("SS01"))
     else: