Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOC: fix punctuation in Timestamp/Timedelta docstrings #28053

Merged
merged 10 commits into from
Sep 28, 2019
+14 −14
Merged

DOC: fix punctuation in Timestamp/Timedelta docstrings #28053

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
02c7720
Add punctuation to IntervalArray docstrings
sparalic Aug 20, 2019
2924cc5
Merge remote-tracking branch 'upstream/master' into Interval-array
sparalic Aug 20, 2019
6f5cc3f
Revert "Add punctuation to IntervalArray docstrings"
sparalic Aug 21, 2019
e9dd483
Add punctuation to Timestamp and Timedelta docstring
sparalic Aug 21, 2019
7807c63
merge upstream
sparalic Aug 21, 2019
1501818
add punctuation to docstrings
sparalic Aug 31, 2019
968b59f
fix errors in test_nat docstrings
sparalic Aug 31, 2019
6c023b0
add period to nattype round docstring
sparalic Sep 28, 2019
212c919
add periods to NaT methods that overlapped with Timestamp
sparalic Sep 28, 2019
a9832cb
remove extra period in Timestamp.replace return docstring
sparalic Sep 28, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions pandas/_libs/tslibs/nattype.pyx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -545,7 +545,7 @@ class NaTType(_NaT):
""")
round = _make_nat_func('round', # noqa:E128
"""
Round the Timestamp to the specified resolution
Round the Timestamp to the specified resolution.

Parameters
----------
Expand Down Expand Up @@ -583,7 +583,7 @@ default 'raise'
""")
floor = _make_nat_func('floor', # noqa:E128
"""
return a new Timestamp floored to this resolution
return a new Timestamp floored to this resolution.

Parameters
----------
Expand Down Expand Up @@ -617,7 +617,7 @@ default 'raise'
""")
ceil = _make_nat_func('ceil', # noqa:E128
"""
return a new Timestamp ceiled to this resolution
return a new Timestamp ceiled to this resolution.

Parameters
----------
Expand Down Expand Up @@ -729,7 +729,7 @@ default 'raise'
""")
replace = _make_nat_func('replace', # noqa:E128
"""
implements datetime.replace, handles nanoseconds
implements datetime.replace, handles nanoseconds.

Parameters
----------
Expand Down
8 changes: 4 additions & 4 deletions pandas/_libs/tslibs/timedeltas.pyx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1150,7 +1150,7 @@ cdef class _Timedelta(timedelta):
"""
Format Timedelta as ISO 8601 Duration like
``P[n]Y[n]M[n]DT[n]H[n]M[n]S``, where the ``[n]`` s are replaced by the
values. See https://en.wikipedia.org/wiki/ISO_8601#Durations
values. See https://en.wikipedia.org/wiki/ISO_8601#Durations.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@datapythonista I'm never sure what to do with URLs at the end of a sentence. Has this been discussed?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jbrockmendel I wasn't sure either, but this seem to have trigger the error for the Timedelta.isoformat docstring.

@datapythonista updated my branch and the CI still failed.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sparalic can you build the html page of that docstring? IIRC you can build that page only with ./doc/make.py --single=pandas.Timedelta.isoformat (building all the docs takes some time). This way we can see if the dot is added to the url link and breaks it, or if Sphinx is smart enough and does what we want.

Looks like there are tests that check those docstrings, you'll have to update them to pass the CI. Let me know if you need help finding the errors in the CI logs...

Thanks!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@datapythonista I was able to sucessfylly build the html page for Timedelta.isoformat without any warnings. So it seems like Sphinx was smart enough to ignore the period on the end.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you open it with a browser, and paste here a screenshot? I don't think Sphinx will warn, it could just create a link with the period in it, that is broken.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The link is created correctly.


.. versionadded:: 0.20.0

Expand Down Expand Up @@ -1314,7 +1314,7 @@ class Timedelta(_Timedelta):

def round(self, freq):
"""
Round the Timedelta to the specified resolution
Round the Timedelta to the specified resolution.

Parameters
----------
Expand All @@ -1332,7 +1332,7 @@ class Timedelta(_Timedelta):

def floor(self, freq):
"""
return a new Timedelta floored to this resolution
return a new Timedelta floored to this resolution.

Parameters
----------
Expand All @@ -1342,7 +1342,7 @@ class Timedelta(_Timedelta):

def ceil(self, freq):
"""
return a new Timedelta ceiled to this resolution
return a new Timedelta ceiled to this resolution.

Parameters
----------
Expand Down
12 changes: 6 additions & 6 deletions pandas/_libs/tslibs/timestamps.pyx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -441,7 +441,7 @@ class Timestamp(_Timestamp):

def round(self, freq, ambiguous='raise', nonexistent='raise'):
"""
Round the Timestamp to the specified resolution
Round the Timestamp to the specified resolution.

Parameters
----------
Expand Down Expand Up @@ -483,7 +483,7 @@ default 'raise'

def floor(self, freq, ambiguous='raise', nonexistent='raise'):
"""
return a new Timestamp floored to this resolution
return a new Timestamp floored to this resolution.

Parameters
----------
Expand Down Expand Up @@ -519,7 +519,7 @@ default 'raise'

def ceil(self, freq, ambiguous='raise', nonexistent='raise'):
"""
return a new Timestamp ceiled to this resolution
return a new Timestamp ceiled to this resolution.

Parameters
----------
Expand Down Expand Up @@ -556,7 +556,7 @@ default 'raise'
@property
def tz(self):
"""
Alias for tzinfo
Alias for tzinfo.
"""
return self.tzinfo

Expand Down Expand Up @@ -754,7 +754,7 @@ default 'raise'
def resolution(self):
"""
Return resolution describing the smallest difference between two
times that can be represented by Timestamp object_state
times that can be represented by Timestamp object_state.
"""
# GH#21336, GH#21365
return Timedelta(nanoseconds=1)
Expand Down Expand Up @@ -893,7 +893,7 @@ default 'raise'
hour=None, minute=None, second=None, microsecond=None,
nanosecond=None, tzinfo=object, fold=0):
"""
implements datetime.replace, handles nanoseconds
implements datetime.replace, handles nanoseconds.

Parameters
----------
Expand Down