Repository: pandas-dev/pandas

Issue:
DOC: Improve error message when the docstring sections are in the wrong order
When checking for errors with `scripts/validate_docstrings.py`, one of the checks is to make sure that the sections are in the right order. But so far we didn't find a great way to report the error, so the user quickly knows what needs to be changed (see discussion in https://github.com/pandas-dev/pandas/pull/23607#discussion_r232697901).

For example, if the sections in the docstring are:
```
See Also
Returns
Examples
```

The reported error is:
```
pandas.Series.infer_objects: Wrong order of sections. "Returns" should be located before "Yields", the right order is: Parameters > Attributes > Methods > Returns > Yields > Other Parameters > Raises > Warns > See Also > Notes > References > Examples
```

A better option is probably to simply return the sections in the docstring in the right order:
```
pandas.Series.infer_objects: Sections are in the wrong order. Correct order is: Returns, See Also, Examples
```

CC: @TomAugspurger 
DOC: Improve error message when the docstring sections are in the wrong order
When checking for errors with `scripts/validate_docstrings.py`, one of the checks is to make sure that the sections are in the right order. But so far we didn't find a great way to report the error, so the user quickly knows what needs to be changed (see discussion in https://github.com/pandas-dev/pandas/pull/23607#discussion_r232697901).

For example, if the sections in the docstring are:
```
See Also
Returns
Examples
```

The reported error is:
```
pandas.Series.infer_objects: Wrong order of sections. "Returns" should be located before "Yields", the right order is: Parameters > Attributes > Methods > Returns > Yields > Other Parameters > Raises > Warns > See Also > Notes > References > Examples
```

A better option is probably to simply return the sections in the docstring in the right order:
```
pandas.Series.infer_objects: Sections are in the wrong order. Correct order is: Returns, See Also, Examples
```

CC: @TomAugspurger 


Discussion:

Resolving patch:
diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py
--- a/scripts/validate_docstrings.py
+++ b/scripts/validate_docstrings.py
@@ -74,8 +74,8 @@
             'whitespace only',
     'GL06': 'Found unknown section "{section}". Allowed sections are: '
             '{allowed_sections}',
-    'GL07': 'Wrong order of sections. "{wrong_section}" should be located '
-            'before "{goes_before}", the right order is: {sorted_sections}',
+    'GL07': 'Sections are in the wrong order. Correct order is: '
+            '{correct_sections}',
     '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',
@@ -599,24 +599,18 @@ def validate_one(func_name):
         if re.match("^ *\t", line):
             errs.append(error('GL05', line_with_tabs=line.lstrip()))
 
-    unseen_sections = list(ALLOWED_SECTIONS)
-    for section in doc.section_titles:
-        if section not in ALLOWED_SECTIONS:
-            errs.append(error('GL06',
-                              section=section,
-                              allowed_sections=', '.join(ALLOWED_SECTIONS)))
-        else:
-            if section in unseen_sections:
-                section_idx = unseen_sections.index(section)
-                unseen_sections = unseen_sections[section_idx + 1:]
-            else:
-                section_idx = ALLOWED_SECTIONS.index(section)
-                goes_before = ALLOWED_SECTIONS[section_idx + 1]
-                errs.append(error('GL07',
-                                  sorted_sections=' > '.join(ALLOWED_SECTIONS),
-                                  wrong_section=section,
-                                  goes_before=goes_before))
-                break
+    unexpected_sections = [section for section in doc.section_titles
+                           if section not in ALLOWED_SECTIONS]
+    for section in unexpected_sections:
+        errs.append(error('GL06',
+                          section=section,
+                          allowed_sections=', '.join(ALLOWED_SECTIONS)))
+
+    correct_order = [section for section in ALLOWED_SECTIONS
+                     if section in doc.section_titles]
+    if correct_order != doc.section_titles:
+        errs.append(error('GL07',
+                          correct_sections=', '.join(correct_order)))
 
     if not doc.summary:
         errs.append(error('SS01'))


Test patch:
diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py
--- a/scripts/tests/test_validate_docstrings.py
+++ b/scripts/tests/test_validate_docstrings.py
@@ -738,8 +738,8 @@ def test_bad_generic_functions(self, func):
         ('BadGenericDocStrings', 'unknown_section',
          ('Found unknown section "Unknown Section".',)),
         ('BadGenericDocStrings', 'sections_in_wrong_order',
-         ('Wrong order of sections. "See Also" should be located before '
-          '"Notes"',)),
+         ('Sections are in the wrong order. Correct order is: Parameters, '
+          'See Also, Examples',)),
         ('BadSeeAlso', 'desc_no_period',
          ('Missing period at end of description for See Also "Series.iloc"',)),
         ('BadSeeAlso', 'desc_first_letter_lowercase',