[jira] [Comment Edited] (ARROW-15006) [Python][Doc] Iteratively enable more numpydoc checks

["Joris Van den Bossche (Jira)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/ARROW-15006?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17600800#comment-17600800 ] 

Joris Van den Bossche edited comment on ARROW-15006 at 9/6/22 2:36 PM:
-----------------------------------------------------------------------

Nice overview! I think your proposal for candidate checks to enable/update looks quite sensible, thanks for that (added a few comments).

(personally not sure this requires a mailing list discussion, as it are relatively minor changes on its own, and only about documentation)


was (Author: jorisvandenbossche):
Nice overview! I think your proposal for candidate checks to enable/update looks quite sensible, thanks for that (added a few comments).



> [Python][Doc] Iteratively enable more numpydoc checks
> -----------------------------------------------------
>
>                 Key: ARROW-15006
>                 URL: https://issues.apache.org/jira/browse/ARROW-15006
>             Project: Apache Arrow
>          Issue Type: Improvement
>          Components: Documentation, Python
>            Reporter: Krisztian Szucs
>            Assignee: Bryce Mecum
>            Priority: Major
>              Labels: good-first-issue, pull-request-available
>          Time Spent: 1h 40m
>  Remaining Estimate: 0h
>
> Asof https://github.com/apache/arrow/pull/7732 we're going to have a numpydoc check running on pull requests. There is a single rule enabled at the moment: PR01
> Additional checks we can run:
> {code}
> ERROR_MSGS = {
>     "GL01": "Docstring text (summary) should start in the line immediately "
>             "after the opening quotes (not in the same line, or leaving a "
>             "blank line in between)",
>     "GL02": "Closing quotes should be placed in the line after the last text "
>             "in the docstring (do not close the quotes in the same line as "
>             "the text, or leave a blank line between the last text and the "
>             "quotes)",
>     "GL03": "Double line break found; please use only one blank line to "
>             "separate sections or paragraphs, and do not leave blank lines "
>             "at the end of docstrings",
>     "GL05": 'Tabs found at the start of line "{line_with_tabs}", please use '
>             "whitespace only",
>     "GL06": 'Found unknown section "{section}". Allowed sections are: '
>             "{allowed_sections}",
>     "GL07": "Sections are in the wrong order. Correct order is: {correct_sections}",
>     "GL08": "The object does not have a docstring",
>     "GL09": "Deprecation warning should precede extended summary",
>     "GL10": "reST directives {directives} must be followed by two colons",
>     "SS01": "No summary found (a short summary in a single line should be "
>             "present at the beginning of the docstring)",
>     "SS02": "Summary does not start with a capital letter",
>     "SS03": "Summary does not end with a period",
>     "SS04": "Summary contains heading whitespaces",
>     "SS05": "Summary must start with infinitive verb, not third person "
>             '(e.g. use "Generate" instead of "Generates")',
>     "SS06": "Summary should fit in a single line",
>     "ES01": "No extended summary found",
>     "PR01": "Parameters {missing_params} not documented",
>     "PR02": "Unknown parameters {unknown_params}",
>     "PR03": "Wrong parameters order. Actual: {actual_params}. "
>             "Documented: {documented_params}",
>     "PR04": 'Parameter "{param_name}" has no type',
>     "PR05": 'Parameter "{param_name}" type should not finish with "."',
>     "PR06": 'Parameter "{param_name}" type should use "{right_type}" instead '
>             'of "{wrong_type}"',
>     "PR07": 'Parameter "{param_name}" has no description',
>     "PR08": 'Parameter "{param_name}" description should start with a '
>             "capital letter",
>     "PR09": 'Parameter "{param_name}" description should finish with "."',
>     "PR10": 'Parameter "{param_name}" requires a space before the colon '
>             "separating the parameter name and type",
>     "RT01": "No Returns section found",
>     "RT02": "The first line of the Returns section should contain only the "
>             "type, unless multiple values are being returned",
>     "RT03": "Return value has no description",
>     "RT04": "Return value description should start with a capital letter",
>     "RT05": 'Return value description should finish with "."',
>     "YD01": "No Yields section found",
>     "SA01": "See Also section not found",
>     "SA02": "Missing period at end of description for See Also "
>             '"{reference_name}" reference',
>     "SA03": "Description should be capitalized for See Also "
>             '"{reference_name}" reference',
>     "SA04": 'Missing description for See Also "{reference_name}" reference',
>     "EX01": "No examples section found",
> }
> {code}
> cc [~alenkaf] [~amol-] [~jorisvandenbossche]



--
This message was sent by Atlassian Jira
(v8.20.10#820010)