Wrong/missing code formats in datetime documentation

[yyyyyyyan]

BPO	41281
Nosy	@ezio-melotti, @merwok, @willingc, @JulienPalard, @yyyyyyyan
PRs	gh-85453: Fix missing/wrong backquotes and role texts in datetime documentation #21447

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2020-07-12.05:26:29.849>
labels = ['type-feature', '3.8', '3.9', '3.10', 'docs']
title = 'Wrong/missing code formats in datetime documentation'
updated_at = <Date 2020-07-12.05:29:56.710>
user = 'https://github.com/yyyyyyyan'

bugs.python.org fields:

activity = <Date 2020-07-12.05:29:56.710>
actor = 'yyyyyyyan'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2020-07-12.05:26:29.849>
creator = 'yyyyyyyan'
dependencies = []
files = []
hgrepos = []
issue_num = 41281
keywords = ['patch']
message_count = 1.0
messages = ['373547']
nosy_count = 6.0
nosy_names = ['ezio.melotti', 'eric.araujo', 'docs@python', 'willingc', 'mdk', 'yyyyyyyan']
pr_nums = ['21447']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue41281'
versions = ['Python 3.8', 'Python 3.9', 'Python 3.10']

Linked PRs

• gh-85453: Adapt datetime.rst to devguide recommendations for code snippets and variables #118068
• [3.12] gh-85453: Adapt datetime.rst to devguide recommendations for code snippets and variables (GH-118068) #118244
• gh-85453: Make numeric literals consistent across datetime.rst #118245
• [3.12] gh-85453: Make numeric literals consistent across datetime.rst (GH-118245) #118248
• gh-85453: Consistent backquotes on None occurences across datetime.rst #118282
• [3.12] gh-85453: Consistent backquotes on None occurences across datetime.rst (GH-118282) #118419
• gh-85453: Fix 'time zone' spelling issues across datetime.rst #118449
• gh-85453: Improve variable mark up on datetime.rst #120702
• [3.13] gh-85453: Fix 'timezone' vs. 'time zone' spelling issues in datetime.rst (GH-118449) #121837
• [3.12] gh-85453: Fix 'timezone' vs. 'time zone' spelling issues in datetime.rst (GH-118449) #121838

[yyyyyyyan]

The datetime page in the docs is missing a lot of needed backquotes syntax for inline code samples. There are some wrong role links too, due to ambiguity in the text roles.

[uatach]

hello @erlend-aasland, I would like to help with this

[erlend-aasland]

Great, @uatach, go ahead! Let me know if you have any questions.

[erlend-aasland]

In PR #118068, code formatting was removed from many numeric literals; let's follow up with a PR to make that consistent across datetime.rst. The following lines still contain numeric literals marked up with double backticks:

• L94
• L2564
• L2711

[erlend-aasland]

Remark by Serhiy #118068 (comment) for L373:

I understand what it means, but it would be nice to explain what does "zero" mean. Is it already explained anywhere?

cpython/Doc/library/datetime.rst

Line 373 in 17947e2

Division by zero raises :exc:`ZeroDivisionError`.

[erlend-aasland]

Remark by Serhiy #118068 (comment):

Should not the sentence start with the title case?

cpython/Doc/library/datetime.rst

Lines 347 to 352 in 17947e2

	| ``-t1`` | equivalent to ``timedelta(-t1.days, |
	| | -t1.seconds*, -t1.microseconds)``, |
	| | and to ``t1 * -1``. (1)(4) |
	+--------------------------------+-----------------------------------------------+
	| ``abs(t)`` | equivalent to ``+t`` when ``t.days >= 0``, |
	| | and to ``-t`` when ``t.days < 0``. (2) |

Check the whole file and fix up any incorrect capitalisation.

[erlend-aasland]

Remark by Serhiy #118068 (comment):

Needed a reference to (3).

cpython/Doc/library/datetime.rst

Lines 328 to 330 in 17947e2

	| ``t1 = t2 / f or t1 = t2 / i`` | Delta divided by a float or an int. The result|
	| | is rounded to the nearest multiple of |
	| | timedelta.resolution using round-half-to-even.|

[hugovk]

Remark by Serhiy #118068 (comment) for L373:

I understand what it means, but it would be nice to explain what does "zero" mean. Is it already explained anywhere?

cpython/Doc/library/datetime.rst

Line 373 in 17947e2

Division by zero raises :exc:`ZeroDivisionError`.

I'm not sure if we need to define zero = 0 = nothing?

[uatach]

Just to make sure about the remaining changes from the old closed PR:

• There was a change related to None, most occurrences use backquotes but on L1738, there's a :const:None and, on L2490, there's a None without backquotes
• There were changes related to standardize "timezone" as "time zone"
• There were changes related to italics, like the q and r on L341
• There was a change related to list format of read-only attributes for the table on L288-L296
• There was a change from local datetime to local date and time on L872
• There were a lot of changes related to :class:.timezone, :class:.tzinfo and others

@erlend-aasland I could list these as remaining, not sure if they are all still relevant or if I missed anything

[erlend-aasland]

• There was a change related to None, most occurrences use backquotes but on L1738, there's a :const:None and, on L2490, there's a None without backquotes

We've been fixing up these from time to time, so there is precedent to create a PR to consistently mark up None using double backquotes throughout datetime.rst.

• There were changes related to standardize "timezone" as "time zone"
  [...]
• There was a change from local datetime to local date and time on L872

I'd audit the whole file and collect all spelling issues in a single PR. Making sure the language in the reference is correct, aligns with the Diátaxis principles.

• There were changes related to italics, like the q and r on L341

Those should be marked up as variables using double backticks.

Moreover, all method and function parameters should be marked up in italics.

• There were a lot of changes related to :class:.timezone, :class:.tzinfo and others

We should make sure all these links work as expected; I'd do an audit of all of them and fix any incorrect links. Also, for each reference we should make sure there's not more than one link per paragraph; that is: if tzinfo is referenced twice in a paragraph, only create a link for the first reference.

[serhiy-storchaka]

I added a note about "Division by zero" because "zero" here is not only 0, but a timedelta with zero duration. Is it defined as "zero" anywhere? This value is special, because it is the only timedelta value with false boolean value.

There is also confusing line across one of tables. Either it should be removed, or the cells below it are misplaced.

[ayushman2046]

Is this issue still open? I would like to contribute.

[merwok]

Could the docs editorial board review this?

I am not convinced of the necessity of avoiding timezone or datetime.
Timezone, like filesystem, is a form with a special meaning, now common in normal English to represent the concept.
Things like the current datetime are not common, but they are readily understandable in the context of the python datetime module docs.

[willingc]

@python/editorial-board Please review thoughts on moving from timezone in prose docs to time zone. I'm leaning toward @merwok's perspective that the change is not a necessity. Looking for additional perspective on this.

[gvanrossum]

@python/editorial-board Please review thoughts on moving from timezone in prose docs to time zone. I'm leaning toward @merwok's perspective that the change is not a necessity. Looking for additional perspective on this.

There are already plenty of places where the docs use "time zone" (when referring to the general concept, not the module or object). I Googled and the consensus seems to be that it's two words.

Regarding "datetime" vs. "date time", neither is correct English. IMO the concept ought to be referred to as "date and time", or could possibly shortened as "date/time". But I'm more open to keeping "datetime" as a form of jargon we're inventing. (Though I don't feel that way about "timezone".)

[erlend-aasland]

IMO the concept ought to be referred to as "date and time", [...]

Yes, this is what #118449 proposes.