DOC: Timestamp EX01 errors
State: closed

Example section added for several methods in class [pd.Timestamp](https://github.com/pandas-dev/pandas/blob/1f89b82cc65f512e78b0038975425cc3d0772a05/pandas/_libs/tslibs/timestamps.pyx#L768)

- [X] xref #37875
- [ ] tests added / passed
- [X] passes `black pandas`
- [X] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry


---
Examples added for:

- pandas.Timestamp.asm8
- pandas.Timestamp.day_of_week
- pandas.Timestamp.day_of_year
- pandas.Timestamp.days_in_month
- pandas.Timestamp.is_leap_year
- pandas.Timestamp.is_month_end
- pandas.Timestamp.is_month_start
- pandas.Timestamp.is_quarter_end
- pandas.Timestamp.is_quarter_start
- pandas.Timestamp.is_year_end
- pandas.Timestamp.is_year_start
- pandas.Timestamp.quarter
- pandas.Timestamp.tz
- pandas.Timestamp.week
- pandas.Timestamp.ceil
- pandas.Timestamp.combine
- pandas.Timestamp.day_name
- pandas.Timestamp.floor
- pandas.Timestamp.fromordinal
- pandas.Timestamp.fromtimestamp
- pandas.Timestamp.month_name
- pandas.Timestamp.normalize
- pandas.Timestamp.now
- pandas.Timestamp.replace
- pandas.Timestamp.round
- pandas.Timestamp.strftime
- pandas.Timestamp.timestamp
- pandas.Timestamp.to_numpy
- pandas.Timestamp.to_julian_date
- pandas.Timestamp.to_period
- pandas.Timestamp.to_pydatetime
- pandas.Timestamp.today
- pandas.Timestamp.tz_convert
- pandas.Timestamp.tz_localize
- pandas.Timestamp.utcfromtimestamp
- pandas.Timestamp.utcnow
- pandas.Timestamp.weekday

Labels:
name: Docs
name: Datetime
description: Datetime data dtype

Comments:
From the checks, I believe that there are some docstrings that were not supposed to be changed? 

I am starting to contribute and trying to follow up on this #17327
can you merge master and ping on green (to make sure no failures are real).
Added few changes to [pandas/_libs/tslibs/nattype.pyx](https://github.com/pandas-dev/pandas/blob/master/pandas/_libs/tslibs/nattype.pyx) so the docstrings match (this check is done by test attached below). Should pass the tests now, I'll ping you once the checks finish.

https://github.com/pandas-dev/pandas/blob/456fcb9829f4e8fba200658efff6ba26152009cd/pandas/tests/scalar/test_nat.py#L326
@jreback passing all tests
Sure @jreback, can do that. However, this pull request won't go through the tests as I mentioned before (won't be green). Should we merge it regardless?
@jreback changes reverted
> Sure @jreback, can do that. However, this pull request won't go through the tests as I mentioned before (won't be green). Should we merge it regardless?

oh how is master passing now then?

yeah this needs to be green. ok i guess re-revert. the only thing with the NaT tests is that they should be showing NaT int he examples 
Hi @jreback ,
The test I attach below is checking if the docstrings between methods in  [pandas/_libs/tslibs/nattype.pyx](https://github.com/pandas-dev/pandas/blob/master/pandas/_libs/tslibs/nattype.pyx) and  [pandas/_libs/tslibs/timestamps.pyx](pandas/_libs/tslibs/timestamps.pyx) match. That's why I also used pd.Timestamp instead of pd.NaT.

https://github.com/pandas-dev/pandas/blob/456fcb9829f4e8fba200658efff6ba26152009cd/pandas/tests/scalar/test_nat.py#L326


 Should we maybe change the test [pandas/pandas/tests/scalar/test_nat.py](pandas/pandas/tests/scalar/test_nat.py) in onther PR?
> Hi @jreback ,
> The test I attach below is checking if the docstrings between methods in [pandas/_libs/tslibs/nattype.pyx](https://github.com/pandas-dev/pandas/blob/master/pandas/_libs/tslibs/nattype.pyx) and [pandas/_libs/tslibs/timestamps.pyx](pandas/_libs/tslibs/timestamps.pyx) match. That's why I also used pd.Timestamp instead of pd.NaT.
> 
> https://github.com/pandas-dev/pandas/blob/456fcb9829f4e8fba200658efff6ba26152009cd/pandas/tests/scalar/test_nat.py#L326
> 
> Should we maybe change the test [pandas/pandas/tests/scalar/test_nat.py](pandas/pandas/tests/scalar/test_nat.py) in onther PR?

ok instead let's use the same doc-string, BUT add a NaT example to it, this should make tests pass and make the examples useful.

ping on green.
Error in the following test from [pandas/tests/io/test_gcs.py](https://github.com/pandas-dev/pandas/blob/master/pandas/tests/io/test_gcs.py) in Windows. Not sure what is causing it.


https://github.com/pandas-dev/pandas/blob/5abc06fbb9b9f7cf63059695bf7fa87d9b57df5c/pandas/tests/io/test_gcs.py#L83-L119
On another note:

Hi @jreback, thanks for your feedback.

Let me summarize last commits below.

### 1) `NaT` examples added
I have added examples with NaT in the docstrings of the following functions in [nattype.pyx](
https://github.com/pandas-dev/pandas/blob/master/pandas/_libs/tslibs/nattype.pyx) and [timestamps.pyx](https://github.com/pandas-dev/pandas/blob/master/pandas/_libs/tslibs/timestamps.pyx):

- tz_convert
- tz_localize
- today
- to_pydatetime
- to_numpy
- round
- replace
- now
- month_name
- floor
- day_name
- ceil

Hence, **these methods now have the same docstring in both modules and should pass the tests** :heavy_check_mark:.

### 2) `NaT` examples not added
Next, I have not added `NaT` examples in the following examples as **these methods basically raise a `ValueError` if called from a `NaT` object**. However I have copied the docstrings from [timestamps.pyx](https://github.com/pandas-dev/pandas/blob/master/pandas/_libs/tslibs/timestamps.pyx) (otherwise tests are not passed).

- utcnow
- utcfromtimestamp
- timestamp
- strftime
- fromtimestamp
- fromordinal
- combine
- astimezone

Note that these methods were created using method [`_make_error_func`](https://github.com/pandas-dev/pandas/blob/master/pandas/_libs/tslibs/nattype.pyx#L67) instead of [`_make_nat_func`](https://github.com/pandas-dev/pandas/blob/master/pandas/_libs/tslibs/nattype.pyx#L59) or [`_make_nan_func`](https://github.com/pandas-dev/pandas/blob/master/pandas/_libs/tslibs/nattype.pyx#L51).

As **these methods now have the same docstring in both modules and should pass the tests** :heavy_check_mark:.

---

### 3) Way forward

From here I see three ways out:

A) Review of this PR, iterate and merge.
B) Remove the Example section from all methods listed in 2) in both modules (so docstrings still match), commit, review and merge PR.
C) Review the tests in [test_nat.pyx](https://github.com/pandas-dev/pandas/blob/master/pandas/tests/scalar/test_nat.py). In particular the parametrization of `compare`. Probably another PR is required.

https://github.com/pandas-dev/pandas/blob/11a5a4b1b11ad68999b6d153cca99907db43affe/pandas/tests/scalar/test_nat.py#L319-L334
This pull request is stale because it has been open for thirty days with no activity. Please update or respond to this comment if you're still interested in working on this.
@lucasrodes i am ok prob merging this as is, if you can merge master and ping
@lucasrodes this was close. if you can merge master and see if can get all passing.
Sorry for the late reply @jreback. Will do asap
@jreback merged with master
Sorry for the long delay @lucasrodes . Looks mostly good. One comment otherwise LGTM
@mroeschke Merged with upstream & fixed typos (missing '(' in docstring examples)
Thanks @lucasrodes! Apologies for the long wait getting this one in.