DOC: Fix and validate that deprecation directive is in the right position in the docstrings (#24188)

Author: aqurilla

ci/code_checks.sh

@@ -212,8 +212,8 @@ fi
 ### DOCSTRINGS ###
 if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
 
-    MSG='Validate docstrings (GL06, SS04, PR03, PR05, EX04)' ; echo $MSG
-    $BASE_DIR/scripts/validate_docstrings.py --format=azure --errors=GL06,SS04,PR03,PR05,EX04
+    MSG='Validate docstrings (GL09, GL06, SS04, PR03, PR05, EX04)' ; echo $MSG
+    $BASE_DIR/scripts/validate_docstrings.py --format=azure --errors=GL09,GL06,SS04,PR03,PR05,EX04
     RET=$(($RET + $?)) ; echo $MSG "DONE"
 
 fi

pandas/core/generic.py

@@ -10039,9 +10039,7 @@ def nanptp(values, axis=0, skipna=True):
             cls, 'ptp', name, name2, axis_descr,
             """Returns the difference between the maximum value and the
             minimum value in the object. This is the equivalent of the
-            ``numpy.ndarray`` method ``ptp``.
-
-            .. deprecated:: 0.24.0
+            ``numpy.ndarray`` method ``ptp``.\n\n.. deprecated:: 0.24.0
                 Use numpy.ptp instead""",
             nanptp)
 

pandas/core/indexes/base.py

@@ -2113,12 +2113,12 @@ def get_duplicates(self):
         """
         Extract duplicated index elements.
 
-        Returns a sorted list of index elements which appear more than once in
-        the index.
-
         .. deprecated:: 0.23.0
             Use idx[idx.duplicated()].unique() instead
 
+        Returns a sorted list of index elements which appear more than once in
+        the index.
+
         Returns
         -------
         array-like

pandas/core/indexes/multi.py

@@ -1484,11 +1484,11 @@ def to_hierarchical(self, n_repeat, n_shuffle=1):
         Return a MultiIndex reshaped to conform to the
         shapes given by n_repeat and n_shuffle.
 
+        .. deprecated:: 0.24.0
+
         Useful to replicate and rearrange a MultiIndex for combination
         with another Index with n_repeat items.
 
-        .. deprecated:: 0.24.0
-
         Parameters
         ----------
         n_repeat : int

pandas/core/series.py

@@ -1083,12 +1083,12 @@ def set_value(self, label, value, takeable=False):
         """
         Quickly set single value at passed label.
 
-        If label is not contained, a new object is created with the label
-        placed at the end of the result index.
-
         .. deprecated:: 0.21.0
             Please use .at[] or .iat[] accessors.
 
+        If label is not contained, a new object is created with the label
+        placed at the end of the result index.
+
         Parameters
         ----------
         label : object

pandas/io/stata.py

@@ -119,8 +119,8 @@
 _data_method_doc = """\
 Reads observations from Stata file, converting them into a dataframe
 
-    .. deprecated::
-       This is a legacy method.  Use `read` in new code.
+.. deprecated::
+    This is a legacy method.  Use `read` in new code.
 
 Parameters
 ----------

scripts/tests/test_validate_docstrings.py

@@ -407,6 +407,18 @@ def sections_in_wrong_order(self):
             before Examples.
         """
 
+    def deprecation_in_wrong_order(self):
+        """
+        This docstring has the deprecation warning in the wrong order.
+
+        This is the extended summary. The correct order should be
+        summary, deprecation warning, extended summary.
+
+        .. deprecated:: 1.0
+            This should generate an error as it needs to go before
+            extended summary.
+        """
+
     def method_wo_docstrings(self):
         pass
 
@@ -772,6 +784,8 @@ def test_bad_generic_functions(self, func):
         ('BadGenericDocStrings', 'sections_in_wrong_order',
          ('Sections are in the wrong order. Correct order is: Parameters, '
           'See Also, Examples',)),
+        ('BadGenericDocStrings', 'deprecation_in_wrong_order',
+         ('Deprecation warning should precede extended summary',)),
         ('BadSeeAlso', 'desc_no_period',
          ('Missing period at end of description for See Also "Series.iloc"',)),
         ('BadSeeAlso', 'desc_first_letter_lowercase',

scripts/validate_docstrings.py

@@ -79,6 +79,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',
     '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',
@@ -492,12 +493,14 @@ def first_line_ends_in_dot(self):
         if self.doc:
             return self.doc.split('\n')[0][-1] == '.'
 
+    @property
+    def deprecated_with_directive(self):
+        return '.. deprecated:: ' in (self.summary + self.extended_summary)
+
     @property
     def deprecated(self):
-        pattern = re.compile('.. deprecated:: ')
         return (self.name.startswith('pandas.Panel')
-                or bool(pattern.search(self.summary))
-                or bool(pattern.search(self.extended_summary)))
+                or self.deprecated_with_directive)
 
     @property
     def mentioned_private_classes(self):
@@ -625,6 +628,10 @@ def get_validation_data(doc):
         errs.append(error('GL07',
                           correct_sections=', '.join(correct_order)))
 
+    if (doc.deprecated_with_directive
+            and not doc.extended_summary.startswith('.. deprecated:: ')):
+        errs.append(error('GL09'))
+
     if not doc.summary:
         errs.append(error('SS01'))
     else: