Repository navigation
Closed as duplicate
Labels
docsDocumentation in the Doc dirDocumentation in the Doc direasytype-featureA feature request or enhancementA feature request or enhancement
Description
| BPO | 41281 |
|---|---|
| Nosy | @ezio-melotti, @merwok, @willingc, @JulienPalard, @yyyyyyyan |
| PRs |
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-140715: 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
Metadata
Metadata
Assignees
Labels
docsDocumentation in the Doc dirDocumentation in the Doc direasytype-featureA feature request or enhancementA feature request or enhancement
Projects
- StatusShow more project fieldsDone
Activity
uatach commentedon Apr 18, 2024
hello @erlend-aasland, I would like to help with this
erlend-aasland commentedon Apr 18, 2024
Great, @uatach, go ahead! Let me know if you have any questions.
erlend-aasland commentedon Apr 24, 2024
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:
erlend-aasland commentedon Apr 24, 2024
Remark by Serhiy #118068 (comment) for L373:
cpython/Doc/library/datetime.rst
Line 373 in 17947e2
erlend-aasland commentedon Apr 24, 2024
Remark by Serhiy #118068 (comment):
cpython/Doc/library/datetime.rst
Lines 347 to 352 in 17947e2
Check the whole file and fix up any incorrect capitalisation.
erlend-aasland commentedon Apr 24, 2024
Remark by Serhiy #118068 (comment):
cpython/Doc/library/datetime.rst
Lines 328 to 330 in 17947e2
gh-85453: Adapt datetime.rst to devguide recommendations for code sni…
pythongh-85453: Adapt datetime.rst to devguide recommendations for co…
[3.12] gh-85453: Adapt datetime.rst to devguide recommendations for c…
gh-85453: Make numeric literals consistent across datetime.rst (#118245)
pythongh-85453: Make numeric literals consistent across datetime.rst (p…
[3.12] gh-85453: Make numeric literals consistent across datetime.rst (…
hugovk commentedon Apr 24, 2024
I'm not sure if we need to define zero = 0 = nothing?
uatach commentedon Apr 25, 2024
Just to make sure about the remaining changes from the old closed PR:
None, most occurrences use backquotes but on L1738, there's a:const:Noneand, on L2490, there's aNonewithout backquotes (gh-85453: Consistent backquotes on None occurences across datetime.rst #118282)local datetimetolocal date and timeon L872:class:.timezone,:class:.tzinfoand others (gh-140715: Improve class reference links on datetime.rst #123980)@erlend-aasland I could list these as remaining, not sure if they are all still relevant or if I missed anything
erlend-aasland commentedon Apr 25, 2024
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.
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.
Those should be marked up as variables using double backticks.
Moreover, all method and function parameters should be marked up in italics.
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
tzinfois referenced twice in a paragraph, only create a link for the first reference.serhiy-storchaka commentedon Apr 25, 2024
I added a note about "Division by zero" because "zero" here is not only 0, but a
timedeltawith zero duration. Is it defined as "zero" anywhere? This value is special, because it is the onlytimedeltavalue 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.
gh-85453: Consistent backquotes on None occurences across datetime.rst (
pythongh-85453: Consistent backquotes on None occurences across datet…
[3.12] gh-85453: Consistent backquotes on None occurences across date…
pythongh-85453: Consistent backquotes on None occurences across datet…
pythongh-85453: Consistent backquotes on None occurences across datet…
ayushman2046 commentedon Jul 9, 2024
Is this issue still open? I would like to contribute.
merwok commentedon Jul 9, 2024
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 datetimeare not common, but they are readily understandable in the context of the python datetime module docs.willingc commentedon Jul 12, 2024
@python/editorial-board Please review thoughts on moving from
timezonein prose docs totime zone. I'm leaning toward @merwok's perspective that the change is not a necessity. Looking for additional perspective on this.gvanrossum commentedon Jul 12, 2024
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 commentedon Jul 12, 2024
Yes, this is what #118449 proposes.
gh-85453: Fix 'timezone' vs. 'time zone' spelling issues in datetime.…
pythongh-85453: Fix 'timezone' vs. 'time zone' spelling issues in dat…
pythongh-85453: Fix 'timezone' vs. 'time zone' spelling issues in dat…
[3.12] gh-85453: Fix 'timezone' vs. 'time zone' spelling issues in da…
pythongh-85453: Fix 'timezone' vs. 'time zone' spelling issues in dat…
[3.13] gh-85453: Fix 'timezone' vs. 'time zone' spelling issues in da…
gh-85453: Improve instance attributes mark up on datetime.rst (#123655)
pythongh-85453: Improve instance attributes mark up on datetime.rst (p…
pythongh-85453: Improve instance attributes mark up on datetime.rst (p…
[3.12] gh-85453: Improve instance attributes mark up on datetime.rst (G…
[3.13] gh-85453: Improve instance attributes mark up on datetime.rst (G…
gh-85453: Improve variable mark up for datetime.rst (#120702)
pythongh-85453: Improve variable mark up for datetime.rst (pythonGH-1…
pythongh-85453: Improve variable mark up for datetime.rst (pythonGH-1…
[3.13] gh-85453: Improve variable mark up for datetime.rst (GH-120702) (
[3.12] gh-85453: Improve variable mark up for datetime.rst (GH-120702) (
str*timeto C11 format codes #140715