DOC: Validate the Returns section in the docstrings

[datapythonista]

scripts/validate_docstrings.py validates that the content of a docstring follows our standards. There are still some of those standards that the script does not validate, and this gives the users the wrong impression that the docstring is all right, when it's not really the case. All the missing validations are listed in #20298.

The format of the Returns section consists of a first line with just the type, and afterwards indented the description. In the case a tuple is returned, then the format is name : type or types for each parameter, and indented descriptions after them. The descriptions need to start with a capital letter and finish with a period. See: https://pandas.pydata.org/pandas-docs/stable/contributing_docstring.html#section-4-returns-or-yields

For this issue is required:

• Change scripts/validate_docstings.py to give errors if some of the described formats are not satisfied.
• Add tests in scripts/tests/test_validate_docstrings.py

[hongshaoyang]

would like to try taking this on!

few questions:

1. how can i use test_validate_docstrings.py to create bad docstrings and use it in the validate_docstrings script?
2. how can i know the structure of doc.returns or doc.yields?

[datapythonista]

To run the tests you should simply call (in a pandas dev environment, and in the project root): python -m pytest scripts if I'm not wrong.

If you want to know the value of variables in the validate_docstrings.py script, you can run it, and add print(whatever) in a line where it contains the value. You can run the script like ./scripts/validate_docstrings.py pandas.DataFrame.head to run just one docstring and make it easier. Is this what you're asking?

[hongshaoyang]

thanks for the quick response! so technically, the docstring for pandas.DataFrame.head should fail? here's the Returns section:

Returns
-------
obj_head : same type as caller
    The first `n` rows of the caller object.

And according to https://pandas.pydata.org/pandas-docs/stable/contributing_docstring.html#section-4-returns-or-yields

But in this case, no name will be provided, unless the method returns or yields more than one value (a tuple of values).

So the Returns section should not provide a name for its return value?

[datapythonista]

In this case it should fail because there is a single value being returned, and it contains the name obj_head.

The correct cases are:

Returns
--------
int
    The single integer value that the function returns.

Returns
--------
id : int
    The function returns a tuple, and the first value is an integer with the id.
name : str
    The second value of the tuple is a string with the name.

[igorfassen]

I've added some checks in validate_docstrings.py, and some corresponding tests.

i've created the following pull request : #23432

(sorry, i'm not very familiar with github, i hope I've done this the right way...)