DOCS: Errors PR08 PR09 in pandas.Period

[HughKelley]

Subset of #28602 (PR09) and #25232 (PR08) for #27977 (docstrings validation).

pandas/_libs/tslibs/period.pyx

python scripts/validate_docstrings.py --errors=PR08
python scripts/validate_docstrings.py --errors=PR09
python scripts/validate_docstrings.py pandas.Period

pandas.Period: Parameter "value" description should finish with "."
pandas.Period: Parameter "freq" description should finish with "."
pandas.Period.asfreq: Parameter "how" description should finish with "."
pandas.Period.to_timestamp: Parameter "freq" description should finish with "."
pandas.Period.to_timestamp: Parameter "how" description should finish with "."
pandas.PeriodDtype: Parameter "freq" description should finish with "."
pandas.Period.to_timestamp: Parameter "how" description should start with a capital letter

10 Errors found:
	Parameters {ordinal} not documented
	Parameter "value" description should finish with "."
	Parameter "freq" description should finish with "."
	Parameter "year" has no description
	Parameter "month" has no description
	Parameter "quarter" has no description
	Parameter "day" has no description
	Parameter "hour" has no description
	Parameter "minute" has no description
	Parameter "second" has no description

[HughKelley]

@datapythonista, quick question,

I intended to start working on this, but when I edit lines 2382 through 2405 of period.pyx and run validate_docstrings.py again there is no change.

I searched the repo for 4Q2005 from the docstring and it only appears once, in that file. Should I be editing the docstring somewhere else? Is there anything else I should check to confirm that I'm editing the correct file?

I double checked that i'm saving the file before validating it again and I tried rebuilding the docs again to no effect.

Thanks!

Here's the full output from python validate_docstrings.py pandas.Period

python scripts/validate_docstrings.py pandas.Period

################################################################################
########################## Docstring (pandas.Period)  ##########################
################################################################################

Represents a period of time.

Parameters
----------
value : Period or str, default None
    The time period represented (e.g., '4Q2005')
freq : str, default None
    One of pandas period strings or corresponding objects
year : int, default None
month : int, default 1
quarter : int, default None
day : int, default 1
hour : int, default 0
minute : int, default 0
second : int, default 0

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

10 Errors found:
	Parameters {ordinal} not documented
	Parameter "value" description should finish with "."
	Parameter "freq" description should finish with "."
	Parameter "year" has no description
	Parameter "month" has no description
	Parameter "quarter" has no description
	Parameter "day" has no description
	Parameter "hour" has no description
	Parameter "minute" has no description
	Parameter "second" has no description
3 Warnings found:
	No extended summary found
	See Also section not found
	No examples section found

[datapythonista]

We get the docstring content by importing the code and checking what's in its __doc__ attribute. So, to give an idea, this could happen:

def foo():
    pass
foo.__doc__ = str(datetime.datetime.now())

This means, that for Cython code, the code needs to be converted to C, compiled, executed, and then we obtain the __doc__ attributes (instead of just being obtained from the pyx files.

What this means for you is that if you change the pyx file, you need to recompile pandas (python setup.py build_ext --inplace) for the validate script to check the changes, and not the old version.

[HughKelley]

@datapythonista a couple more questions

Should I be running PEP8 validation before submitting a pull request or is it sufficient to rely on the script here?

In pandas.Period.to_timestamp and pandas.PeriodDtype there is 1 remaining error:

Unknown parameters {freq, how}

These are clearly the parameters used in the function definition and I looked for some formatting thing that might cause the script to not recognize them but didn't come up with anything.

Is there an obvious fix to that?

[datapythonista]

Running pep8 locally can save you time, since the CI requires pushing and takes like half an hour. But should be the same other than that.

I'm in my phone and can't look the code now. If those parameters are not detected by the script, may be an error of the script. When a function is wrapped liked with a decorator, some machinery is required to get the right function to extract the parameters from. Some prints can help you better understand what's going on when calling the validation for that function.