gh-85453: Fix missing/wrong backquotes and role texts in datetime documentation

[yyyyyyyan]

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

• Issue: Wrong/missing code formats in datetime documentation #85453

[nanjekyejoannah]

Am curious, why the "." before every item i.e classes, fields etc

[yyyyyyyan]

@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

See also method :meth:`time` 

which ends up linking to the module time. Prefixing the dot specifies we're in datetime.datetime class scope and therefore the only possible link is to the datetime.datetime.time() method.

[serverwentdown]

Reviewed this, I think this is a significant improvement, but also I left some considerations.

[serverwentdown]

Personally, I'd disagree with these changes as these numbers aren't code.

[serverwentdown]

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.

[serverwentdown]

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.

[serverwentdown]

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.

[serverwentdown]

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.

[slateny]

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.

[erlend-aasland]

Please split this up in smaller parts. Try to keep the diff within ~200 lines of code for each PR.

[ghost]

The following commit authors need to sign the Contributor License Agreement:

• [email protected]

Click the button to sign:

[nanjekyejoannah]

Why should we split a PR on a single topic especially a docs PR @erlend-aasland ?

Is this rule new since I haven't been following core dev stuff due to my schedule these days.
I have seen bigger PRs before.

[nanjekyejoannah]

I reopened in error, sorry

[erlend-aasland]

Why should we split a PR on a single topic especially a docs PR @erlend-aasland ?

The PR does more than the title says:

• fix typos
• fix incorrect markup syntax (backquotes)
• change markup syntax from one style to another
• add new markup where no markup was used
• change formatting (reformat a table as a list)
• improve Sphinx roles

We advocate making atomic code and documentation changes. A PR that consists of many different types of changes is hard to review and has a high risk of becoming a stale PR.

Is this rule new since I haven't been following core dev stuff due to my schedule these days.

I guess so. The last one or two years, we've chosen to adapt Diátaxis as our north star for documentation. Among other things, it advocates to carry out smaller changes in iterations.

Moreover, the diff is so large that even GitHub does not show it by default.

Back to the PR: some of these changes are trivial, and would be easy to review and merge as separate PRs; other changes are non-trivial, and require more discussion IMO; lastly, another part of the changes are IMO style changes that are perhaps not needed.