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
• gh-85453: Improve instance attributes mark up on datetime.rst #123655
• [3.13] gh-85453: Improve instance attributes mark up on datetime.rst (GH-123655) #123740
• [3.12] gh-85453: Improve instance attributes mark up on datetime.rst (GH-123655) #123741
• gh-85453: Improve class reference links on datetime.rst #123980
• [3.13] gh-85453: Improve variable mark up for datetime.rst (GH-120702) #125490
• [3.12] gh-85453: Improve variable mark up for datetime.rst (GH-120702) #125491

[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.|

[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.