DOC: fix docstring validation errors for pandas.Timedelta/pandas.TimedeltaIndex

[natmokval]

follow up on issues #56804, #59458 and #58063
pandas has a script for validating docstrings:

pandas/ci/code_checks.sh

Lines 112 to 128 in 2244402

	-i "pandas.Timedelta.asm8 SA01" \
	-i "pandas.Timedelta.ceil SA01" \
	-i "pandas.Timedelta.components SA01" \
	-i "pandas.Timedelta.floor SA01" \
	-i "pandas.Timedelta.max PR02" \
	-i "pandas.Timedelta.min PR02" \
	-i "pandas.Timedelta.resolution PR02" \
	-i "pandas.Timedelta.round SA01" \
	-i "pandas.Timedelta.to_numpy PR01" \
	-i "pandas.Timedelta.to_timedelta64 SA01" \
	-i "pandas.Timedelta.total_seconds SA01" \
	-i "pandas.Timedelta.view SA01" \
	-i "pandas.TimedeltaIndex.components SA01" \
	-i "pandas.TimedeltaIndex.microseconds SA01" \
	-i "pandas.TimedeltaIndex.nanoseconds SA01" \
	-i "pandas.TimedeltaIndex.seconds SA01" \
	-i "pandas.TimedeltaIndex.to_pytimedelta RT03,SA01" \

Currently, some methods fail docstring validation check.
The task here is:

• take 2-4 methods
• run: scripts/validate_docstrings.py <method-name>
• run pytest pandas/tests/scalar/test_nat.py::test_nat_doc_strings
• fix the docstrings according to whatever error is reported
• remove those methods from code_checks.sh script
• commit, push, open pull request

Example:

 scripts/validate_docstrings.py pandas.Timedelta.ceil

pandas.Timedelta.ceil fails with the SA01 and ES01 errors

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

2 Errors found for `pandas.Timedelta.ceil`:
        ES01    No extended summary found
        SA01    See Also section not found

Please don't comment take as multiple people can work on this issue. You also don't need to ask for permission to work on this, just comment on which methods are you going to work.

If you're new contributor, please check the contributing guide

[TheRockStarDBA]

take

[doshi-kevin]

Working on --i "pandas.Timedelta.asm8 SA01" \

[doshi-kevin]

Hey @natmokval I tried running 'scripts/validate_docstrings.py pandas.Timedelta.ceil' command on my terminal. But I dont know why it doesnt execute.

[NavaneetthaSundararaj]

I would like to work on:

-i "pandas.TimedeltaIndex.nanoseconds SA01" \
-i "pandas.TimedeltaIndex.seconds SA01" \
-i "pandas.TimedeltaIndex.to_pytimedelta RT03,SA01" \

[ivonastojanovic]

I'll work on these:

 -i "pandas.Timedelta.components SA01" \ 
 -i "pandas.Timedelta.floor SA01" \ 
 -i "pandas.Timedelta.max PR02" \ 
 -i "pandas.Timedelta.min PR02" \ 

[doshi-kevin]

Hey @ivonastojanovic , could you please tell me how to solve this issue, I really want to be a contributor here but for some reason scripts/validate_docstrings.py command doesnt work. (I have tried to put different functions in place, if anyone could help me... :)

[ivonastojanovic]

Hey @ivonastojanovic , could you please tell me how to solve this issue, I really want to be a contributor here but for some reason scripts/validate_docstrings.py command doesnt work. (I have tried to put different functions in place, if anyone could help me... :)

Hey @doshi-kevin, when you run scripts/validate_docstrings.py pandas.Timedelta.ceil, what do you get as output? You should get something like this:

$ scripts/validate_docstrings.py pandas.Timedelta.ceil
+ /home/codespace/.python/current/bin/ninja
[1/1] Generating write_version_file with a custom command

################################################################################
###################### Docstring (pandas.Timedelta.ceil)  ######################
################################################################################

Return a new Timedelta ceiled to this resolution.

Parameters
----------
freq : str
    Frequency string indicating the ceiling resolution.
    It uses the same units as class constructor :class:`~pandas.Timedelta`.

Examples
--------
>>> td = pd.Timedelta('1001ms')
>>> td
Timedelta('0 days 00:00:01.001000')
>>> td.ceil('s')
Timedelta('0 days 00:00:02')

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

2 Errors found for `pandas.Timedelta.ceil`:
        ES01    No extended summary found
        SA01    See Also section not found

At the bottom you see 2 errors, you shouldn't do anything about ES01, but you should fix SA01. pandas.Timedelta.ceil method is missing 'See Also' section which you should add. Try to locate the method first and then add references to related methods, classes, attributes to 'See Also' section.

[doshi-kevin]

That's what the problem is, I forked the repo, kept it upstream and ran this command.
The thing is nothing happens after that, the terminal just stops ....
Maybe I need to fork the repo once again

[doshi-kevin]

I don't understand why this is happening, the code does not give me any output.

[fbourgey]

Working on

"pandas.Timedelta.round SA01"
"pandas.Timedelta.to_timedelta64 SA01"
"pandas.Timedelta.total_seconds SA01"
"pandas.Timedelta.view SA01"

[uditbaliyan]

sorry i forgot to mention on which methods i was working
but i have created pull request for this method
"pandas.Timedelta.round SA01"
@fbourgey

[amanlai]

Working on

 -i "pandas.Timedelta.to_numpy PR01" \ 
 -i "pandas.TimedeltaIndex.components SA01" \ 
 -i "pandas.TimedeltaIndex.microseconds SA01" \

[ammar-qazi]

Working on

-i "pandas.Timedelta.ceil SA01" \ 

I installed a whole operating system for this :).

[ammar-qazi]

Working on

-i "pandas.Timedelta.ceil SA01" \ 

I installed a whole operating system for this :).

I guess @uditbaliyan already completed this.

[amanlai]

@ammar-qazi If you have time, could you take pandas.Timedelta.resolution? I initially wanted to take it but I can't find its docstring.

[ammar-qazi]

Thank you, @amanlai. I'll take pandas.Timedelta.resolution then.

[ammar-qazi]

@ivonastojanovic I might have resolved the following in my commit for pandas.Timedelta.resolution.

 -i "pandas.Timedelta.max PR02" \ 
 -i "pandas.Timedelta.min PR02" \ 

That said, I'm not sure because there's no definitive docstring, as @amanlai already mentioned.

Min, max, and resolution are probably attributes being defined by cdef class _Timedelta(timedelta) and MinMaxReso. As a result, I don't know how to exactly handle it.

Alternatively, we can get the docs to show up after compilation by adding the docstring to timedeltas.pyi instead of timedeltas.pyx. However, I don't think that's the recommended way.

[saldanhad]

working on #59914

-i "pandas.TimedeltaIndex.to_pytimedelta RT03,SA01" \

[Manju080]

Working on -i "pandas.Timedelta.components SA01" \

[Ravenin7]

@doshi-kevin I was having the same problem, but writing "python" before scripts/validate_docstrings.py worked to actually execute the file.

[Ravenin7]

@ammar-qazi Are you still working on the following or can I take them -

-i "pandas.Timedelta.resolution PR02" \
-i "pandas.Timedelta.max PR02" \
-i "pandas.Timedelta.min PR02" \

It appears that your PR was waiting for review, then closed because you didn't update it with the suggested fixes.

[ammar-qazi]

@Ravenin7 It didn't receive a review for quite a while, so I forgot about it. I just tried once again.

[ammar-qazi]

@Ravenin7 On second thoughts, you can take it. I'm not 100% sure what's the right way to document attributes created by MinMaxReso, so I'd love to see how you approach it.

[Ravenin7]

@ammar-qazi I couldn't push the requested changes to your PR due to lack of permissions, so I have created a new PR #60283 to address them.

[ammar-qazi]

@Ravenin7 Thank you. That said, it still leads to an error docstring validation — I don't know the solution to that. That's why I left it.