Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Validation rule GL09 failing #573

Open
pp-mo opened this issue Jul 17, 2024 · 2 comments · May be fixed by #575
Open

Validation rule GL09 failing #573

pp-mo opened this issue Jul 17, 2024 · 2 comments · May be fixed by #575

Comments

@pp-mo
Copy link

pp-mo commented Jul 17, 2024

I can't work out how to satisfy GL09 when including a deprecation notice.

Demonstration

For example:

file "sample_code.py"

def my_func_wrong():
    """Compute my function.

    What it does in more detail.

    .. deprecated:: v0.1
        This function is listed for future removal.
    """
    pass

def my_func_right():
    """Compute my function.

    .. deprecated:: v0.1
        This function is listed for future removal.

    What it does in more detail.
    """
    pass

produces ...

+-----------------------------------------------+---------------------------+---------+---------------------------------------------+
| file                                          | item                      | check   | description                                 |
+===============================================+===========================+=========+=============================================+
| lib/iris/experimental/ugrid/sample_code.py:1  | sample_code.my_func_wrong | GL09    | Deprecation warning should precede extended |
|                                               |                           |         | summary                                     |
+-----------------------------------------------+---------------------------+---------+---------------------------------------------+
| lib/iris/experimental/ugrid/sample_code.py:11 | sample_code.my_func_right | GL09    | Deprecation warning should precede extended |
|                                               |                           |         | summary                                     |
+-----------------------------------------------+---------------------------+---------+---------------------------------------------+

Expected

I think the form in "my_func_right" ought to pass OK.

Workaround

For now, in the Iris project, we are putting all our "deprecated" sections within a "Notes" section,
and have been since we since we adopted numpydoc-validation in pre-commit.
For example here
But this feels like a kluge.
stefanv added a commit to stefanv/numpydoc that referenced this issue Jul 17, 2024
@stefanv
Dedent section starting with .. deprecation::
ed037cf 
Closes numpy#573
@stefanv stefanv linked a pull request Jul 17, 2024 that will close this issue
Open
@rossbar
Copy link
Contributor

rossbar commented Jul 17, 2024

Thanks for reporting - this seems like a bug in the validator. I agree that my_func_right should be passing the validation.

@pp-mo
Copy link
Author

pp-mo commented Jul 18, 2024

Thanks for reporting - this seems like a bug in the validator. I agree that my_func_right should be passing the validation.

Thanks for such a fast response !
It's useful just to have that confirmed (as my grasp of RST is a bit shaky TBH)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Dedent section starting with .. deprecation:: stefanv/numpydoc
2 participants
@rossbar @pp-mo