[ARROW-15006] [Python][Doc] Iteratively enable more numpydoc checks

• Type: Improvement
• Status: In Progress
• Priority: Major
• Resolution: Unresolved
• Component/s: Documentation, Python
• Labels: good-first-issue pull-request-available
• External issue URL: https://github.com/apache/arrow/issues/30525
• Assignee: Bryce Mecum
• Reporter: Krisztian Szucs
• Created: 07/Dec/21 10:59
• Updated: 11/Jan/23 08:43

Description

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:

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",
}

cc alenkaf amol- jorisvandenbossche

Issue Links

• is related to: ARROW-17542 [Python][Dev] Document the process to run numpydoc checks
• links to: GitHub Pull Request #13983
• links to: GitHub Pull Request #15214