DOC: fix PR02 errors in docstrings - pandas.describe_option, pandas.get_option, pandas.reset_option

[jrmylow]

Test results:
Describe_option

$ scripts/validate_docstrings.py --format=actions --errors=PR02 pandas.describe_option
...
################################################################################
################################## Validation ##################################
################################################################################

1 Errors found for `pandas.describe_option`:
        SA01    See Also section not found

Get_option

$ scripts/validate_docstrings.py --format=actions --errors=PR02 pandas.get_option
...
################################################################################
################################## Validation ##################################
################################################################################

2 Errors found for `pandas.get_option`:
        PR01    Parameters {'silent'} not documented
        SA01    See Also section not found

Reset_option

$ scripts/validate_docstrings.py --format=actions --errors=PR02 pandas.reset_option
...
################################################################################
################################## Validation ##################################
################################################################################

2 Errors found for `pandas.reset_option`:
        PR01    Parameters {'silent'} not documented
        SA01    See Also section not found

• Cross-ref: DOC: fix PR02 errors in docstrings #57111
• Tests added and passed if fixing a bug or adding a new feature
• All code checks passed.
• Added type annotations to new arguments/methods/functions.
• Added an entry in the latest doc/source/whatsnew/vX.X.X.rst file if fixing a bug or adding a new feature.

[jrmylow]

Note, set_option is a bit trickier because it accepts any number of pairs of arguments, will investigate more there

[datapythonista]

Thanks for the contribution @jrmylow. I don't understand your changes here. If you're fixing PR02 errors in docstrings, shouldn't we be adding missing parameters to the docs here? I don't know what is the change in the config module, is this intentional?

[jrmylow]

Oh right, I forgot to document the reason for the changes.

From 1, I understand that the PR01/02 errors are for function parameters that haven't been documented, and documented parameters that aren't in a function respectively.

What I found is that the way these methods are constructed means that they have a strange signature, and the use of inspect/signature is meant to rectify that.

Taking pandas.reset_option as an example, the message I get is 3 errors found:

PR01  Parameters {'*args', '**kwargs'} not documented
PR02  Unknown parameters {'pat'}
SA01 See Also section not found

reset_option is not defined directly, instead through a CallableDynamicDoc

pandas/pandas/_config/config.py

Line 451 in 46163c5

reset_option = CallableDynamicDoc(_reset_option, _reset_option_tmpl)

The function _reset_option is defined and its signature includes the parameter pat:

pandas/pandas/_config/config.py

Line 199 in 46163c5

def _reset_option(pat: str, silent: bool = False) -> None:

The docstring _reset_option_tmpl is also defined and references the parameter pat as str/regex:

pandas/pandas/_config/config.py

Line 411 in 46163c5

_reset_option_tmpl = """

pandas/pandas/_config/config.py

Line 424 in 46163c5

pat : str/regex

However, the PR02 error does not recognise that pat exists despite being in both the _reset_option signature and the docstring.

When examining the signature of pandas.reset_option using inspect.signature() I find that it is actually:

>>> inspect signature(pandas.reset_option)
<Signature (*args, **kwds) -> 'T'>

The fix applied has been to copy the function signature (in this case _reset_option and apply it to CallableDynamicDoc)

@datapythonista hope this makes sense, happy to proceed with another method if there is a strong argument against this way

[jrmylow]

Note as a follow-on from the above, the reason this does not fix set_options is that this function actually does accept any number of args and kwargs (contradicting the documentation, which only specifies set_option(pat, value)), and I haven't figured out a clean way to fix this yet.

[datapythonista]

Thanks for clarifying @jrmylow, this wasn't immediately obvious from the diff. This seems reasonable, I guess it's the best fix we can do. Is there anything else missing here? I see this as a draft PR

[jrmylow]

This fix only fixes 3 out of 4 of the options. set_option is tricky because the underlying method signature is in fact _set_option(*args, **kwargs) and contradicts the docstring, which expects set_option(pat, value). I wanted to fix all of them in a single PR given it's the same issue and the same module.

[datapythonista]

I would personally prefer if you address further fixes in new PRs. For reviewers, we'll have to keep reviewing the changes you already have at every iteration if you continue working on this PR, which is not a big problem since the changes are small, but it's still more efficient if we have to review only new changes in the future.

[jrmylow]

Ok fair, I'll un-draft it and wait for the code checks to all pass

[mroeschke]

Thanks @jrmylow