FAQ

Should we fix docstrings that are found in .pyx files?

Yes, docstrings in Cython files (pyx) also need fixing. They are rendered in the documentation in the same exact way. The only difference is that after fixing them, you need to compile pandas for the script to validate the latest version. It's the compiled version of the fixating which is validated.

How do you check whether the reported error is a false positive or not?

Sometimes the validation script reports errors that turn out to be false positives. There are a few reasons why it happens. One of the most often is that the script obtains the wrong object and thus reports the docstring contained in Python instead of pandas. For example, if you want to check whether the reported errors of pandas.tseries.offsets.DateOffset.normalize are false positives or not, you can verify this by running:

./scripts/validate_docstrings.py pandas.tseries.offsets.DateOffset.normalize

You'll find the following:

################################################################################
########### Docstring (pandas.tseries.offsets.DateOffset.normalize)  ###########
################################################################################

bool(x) -> bool

Returns True when the argument x is true, False otherwise.
The builtins True and False are the only two instances of the class bool.
The class bool is a subclass of the class int, and cannot be subclassed.

################################################################################
################################## Validation ##################################
################################################################################

4 Errors found:
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)
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)
Summary does not start with a capital letter
Summary does not end with a period
2 Warnings found:
See Also section not found
No examples section found

The first section displays the docstring that has been detected by the script. In this case, it's the docstring from the python bool() builtin: https://docs.python.org/3.8/library/functions.html#bool. Since this docstring is not in pandas, this is a false positive.