Repository: pandas-dev/pandas

Issue:
DOCS: Errors PR08 PR09 in pandas.Period
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
```
DOCS: Errors PR08 PR09 in pandas.Period
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
```


Discussion:
@datapythonista, quick question,

I intended to start working on this, but when I edit lines 2382 through 2405 of [period.pyx](https://github.com/pandas-dev/pandas/blob/5cbd82bdd3a9d4900849808735a7e2de61bfdf6b/pandas/_libs/tslibs/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
```
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:
```python
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.
@datapythonista, quick question,

I intended to start working on this, but when I edit lines 2382 through 2405 of [period.pyx](https://github.com/pandas-dev/pandas/blob/5cbd82bdd3a9d4900849808735a7e2de61bfdf6b/pandas/_libs/tslibs/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
```
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:
```python
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.

Resolving patch:
diff --git a/pandas/core/dtypes/dtypes.py b/pandas/core/dtypes/dtypes.py
--- a/pandas/core/dtypes/dtypes.py
+++ b/pandas/core/dtypes/dtypes.py
@@ -793,7 +793,7 @@ class PeriodDtype(PandasExtensionDtype):
     Parameters
     ----------
     freq : str or DateOffset
-        The frequency of this PeriodDtype
+        The frequency of this PeriodDtype.
 
     Attributes
     ----------


Test patch: