DOC: Improve error message when the docstring sections are in the wrong order

[datapythonista]

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 #23607 (comment)).

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

[dat-boris]

👋 working on this one as Pycon CA sprint.