bpo-41281: Fix missing/wrong backquotes and role texts in datetime documentation #21447
Conversation
9a4d299
to
325824b
Compare
|
@nanjekyejoannah this is mainly to prevent future ambiguity bugs, but also fixes some current bugs we have now. A quick example is on line 1214 of datetime.rst in master, where we have which ends up linking to the module |
| * A millisecond is converted to ``1000`` microseconds. | ||
| * A minute is converted to ``60`` seconds. | ||
| * An hour is converted to ``3600`` seconds. | ||
| * A week is converted to ``7`` days. |
There was a problem hiding this comment.
Personally, I'd disagree with these changes as these numbers aren't code.
There was a problem hiding this comment.
Actually, I take that back, this is fine. I perceive them as referring to microseconds and not microseconds, seconds and not seconds, etc.
Maybe the arguments in these four lines could be made into italics too.
There was a problem hiding this comment.
All:
- A millisecond is converted to
1000microseconds. - A minute is converted to
60seconds. - An hour is converted to
3600seconds. - A week is converted to
7days.
Or none:
- A millisecond is converted to 1000 microseconds.
- A minute is converted to 60 seconds.
- An hour is converted to 3600 seconds.
- A week is converted to 7 days.
| of the range of values supported by the platform C :c:func:`localtime` | ||
| function, and :exc:`OSError` on :c:func:`localtime` failure. | ||
| It's common for this to be restricted to years from 1970 through 2038. Note | ||
| that on non-POSIX systems that include leap seconds in their notion of a | ||
| timestamp, leap seconds are ignored by :meth:`fromtimestamp`. | ||
| timestamp, leap seconds are ignored by :meth:`.date.fromtimestamp`. |
There was a problem hiding this comment.
I personally think the dots are excessive, because it is very unlikely that a global module named fromtimestamp is going to exist in the future.
There was a problem hiding this comment.
I think the likelihood of ambiguity in the future is quite small, therefore the significant number of changes isn't really justified. For me, I find the docs source code harder to read with all the "."s.
Co-authored-by: Ambrose Chua <ambrose@hey.com>
|
Regarding not splitting up the PR, to the contrary, I would actually recommend at least another PR just for the roles (but perhaps more depending on what remains). At its current state, it's difficult to review due to its length combined with the formatting changes interlaced between the role text changes. |
Also fix some small typos. I know it's a lot of change to review but I really don't think it would be worth to separate these commits in different PRs.
https://bugs.python.org/issue41281