Wrong/missing code formats in datetime documentation

[1cbe5cec-4b17-4d66-8cb1-fd06c7220667]

BPO	41281
Nosy	@ezio-melotti, @merwok, @willingc, @JulienPalard, @yyyyyyyan
PRs	python/cpython#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: ```python assignee = None closed_at = None created_at = labels = ['type-feature', '3.8', '3.9', '3.10', 'docs'] title = 'Wrong/missing code formats in datetime documentation' updated_at = user = 'https://github.com/yyyyyyyan' ``` bugs.python.org fields: ```python activity = actor = 'yyyyyyyan' assignee = 'docs@python' closed = False closed_date = None closer = None components = ['Documentation'] creation = 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-118068
• gh-118244
• gh-118245
• gh-118248
• gh-118282
• gh-118419
• gh-118449
• gh-120702
• gh-121837
• gh-121838
• gh-123655
• gh-123740
• gh-123741
• gh-123980
• gh-125490
• gh-125491

[1cbe5cec-4b17-4d66-8cb1-fd06c7220667]

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 https://github.com/python/cpython/pull/118068#discussion_r1578039286 for L373:

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

https://github.com/python/cpython/blob/17947e2358ee550033c98e51af95548c423c7075/Doc/library/datetime.rst?plain=1#L373

[erlend-aasland]

Remark by Serhiy https://github.com/python/cpython/pull/118068#discussion_r1578037224:

Should not the sentence start with the title case?

https://github.com/python/cpython/blob/17947e2358ee550033c98e51af95548c423c7075/Doc/library/datetime.rst?plain=1#L347-L352

Check the whole file and fix up any incorrect capitalisation.

[erlend-aasland]

Remark by Serhiy https://github.com/python/cpython/pull/118068#discussion_r1576628055:

Needed a reference to (3).

https://github.com/python/cpython/blob/17947e2358ee550033c98e51af95548c423c7075/Doc/library/datetime.rst?plain=1#L328-L330

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

https://github.com/python/cpython/blob/17947e2358ee550033c98e51af95548c423c7075/Doc/library/datetime.rst?plain=1#L373

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:

• [x] 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 (#118282)
• [x] There were changes related to standardize "timezone" as "time zone" (#118449)
• [x] There were changes related to italics, like the q and r on L341 (#120702)
• [x] There was a change related to list format of read-only attributes for the table on L288-L296 (#123655)
• [ ] 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 (#123980)

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