[
https://issues.apache.org/jira/browse/ARROW-15006?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17655607#comment-17655607
]
Bryce Mecum commented on ARROW-15006:
-------------------------------------
I've added five more checks (GL10, PR04, PR05, RT03, YD01) to CI in
[https://github.com/apache/arrow/pull/15214.] I started working on PR06 but ran
into an issue with how we do docstrings for pyarrow.compute functions and how
numpydoc chooses to implement PR06. PR06 checks that you don't use types like
'string' and use 'str' instead. We dynamically generate the docstrings for
pyarrow.compute functions from libarrow compute which uses types like
`MatchSubstringOptions`. This fails PR06 because string is a substring.
I filed an [an issue|https://github.com/numpy/numpydoc/issues/446] and [a
PR|https://github.com/numpy/numpydoc/issues/446] to get this change so we can
add PR06. After that, the remainder we decided to work on are GL08, SS01, and
RT01.
> [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: 5h 50m
> 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)
