DOC: Deprecation directive in docstrings should be placed before the extended summary
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.