DOC: Fix docstring of read_csv and related methods

The next Excel related functions contain many errors as reported by scripts/validate_docstrings.py:

• pandas.read_table
• pandas.read_csv
• pandas.read_fwf

We should fix them, following our standards: https://pandas.pydata.org/pandas-docs/stable/contributing_docstring.html

The validation script should not report errors after they are fixed.

[datapythonista]

For 1, I think there is a missing blank line between the name/type line, and the directive. Not sure if that’s the cause. But I guess it’s related to the .. deprecated:: directive. You can also do a grep of that directive, see if docstrings containing it for a parameter have the same validation error, and if you think it’s a problem in the validation script, ignore the error and create an issue (mention #20298 and myself in the issue, so I add it to the list).

For 2, you can add a couple of prints in the property double_blank_lines for debugging (don’t commit that).One that prints every line, and one that prints when the two blank lines are found. That should give you a better idea of what’s the exact problem.

Let me know if you need help.

[datapythonista]

This one is a bit tricky. We validate that the signature and the documented parameters match. So:

def foo(arg1, **kwargs):
    """
    Parameters
    -----------
    arg1 : str
    arg2 : str
    """

Will generate an error that arg2 is unknown, and kwargs is not documented. Which makes sense.

What happen is that read_fwf was implemented, so most of the parameters are not explicit in the signature, but kwargs is used instead.

Personally, I think the right solution is to change the signature, and add all them. But that’s trickier than just changing the docstrings. Shouldn’t break anything, but it’s more risky than just touching docs.

@jreback any reason why we should not add these parameters to the signature?