Closed
Description
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.pyto 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.pythe new error code, so the new validation is checked in the CI.