DOC: Deprecation directive in docstrings should be placed before the extended summary

[datapythonista]

Based on https://numpydoc.readthedocs.io/en/latest/format.html#sections

This is correct:

def some_old_method():
    """
    This is what old methods does.

    .. deprecated:: 1.0
        Use `some_new_method` instead.

    This is an extended summary with more details about
    what `some_old_method` does.

    The extended summary can contain multiple paragraphs.
    """

This is NOT correct:

def some_old_method():
    """
    This is what old methods does.

    This is an extended summary with more details about
    what `some_old_method` does.

    The extended summary can contain multiple paragraphs.

    .. deprecated:: 1.0
        Use `some_new_method` instead.
    """

But seems like we've been doing it wrong in many cases (see #24105#discussion_r239646516)

What we need to do is:

• Add a validation in scripts/validate_docstrings.py to check that the order is correct (there is a validation for the order of the sections, it may or may not make sense to validate it there or in a new error).
• Add tests to check that the new validation works (in scripts/tests/test_validate_docstrings.py)
• Get the list of all wrong cases (there shouldn't be many, we don't have so much deprecated stuff)
• Fix the wrong cases by moving the .. deprecated:: directive to the correct position.
• Add to the call to the validation script in ci/code_checks.py the new error code, so the new validation is checked in the CI.

[aqurilla]

Hi! @datapythonista, can I work on this issue?

[datapythonista]

sure @aqurilla, let me know if you need help

[aqurilla]

Will do, thanks!