DOC: Validate the order of the sections in the docstrings

[datapythonista]

scripts/validate_docstrings.py validates that the content of a docstring follows our standards. There are still some of those standards that the script does not validate, and this gives the users the wrong impression that the docstring is all right, when it's not really the case. All the missing validations are listed in #20298.

In the docstrings, the order of the sections should be:

• Short summary
• Summary
• Parameters
• Returns or Yields
• See Also
• Notes
• Examples

This is described in:

• Our documentation: https://pandas.pydata.org/pandas-docs/stable/contributing_docstring.html
• The numpydoc standard we follow: https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard

For this issue is required:

• Change scripts/validate_docstings.py
• Add tests in scripts/tests/test_validate_docstrings.py
• Run the script for all docstrings (i.e. ./scripts/validate_docstings.py) and check in the resulting report how many of the docstrings in pandas have the sections in the wrong order (add that information to this issue)
• Test manually that running the validation for one of the wrong cases, produces an output that is useful for the users (the script can be run for one docstring using for example ./scripts/validate_docstings.py pandas.DataFrame.head, and the output is a user-friendly explanation of the errors).

[ryankarlos]

@datapythonista Assuming this is not taken - ill work on this - any other similar ones I can work on - looking to hit my target of 5 PRs this month for the Hacktoberfest t-shirt :)

[datapythonista]

Shouldn't be taken, thanks. Everything is in the issue tracker.