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"