bpo-36960: Make datetime docs more user-friendly #13410

bsolomon1124 · 2019-05-18T20:17:10Z

https://bugs.python.org/issue36960

Appreciate any core reviewer who can take the time to sit down to read through the updated version. While the diff is fairly large in terms of number of commits and lines changed, there are no drastic changes made here and I've made an effort to keep the commits modular and self-documenting.

Last rebased off master as of 2019-06-22.

alessandrocucci

I found some double spaces here and there, but this are small things.
I really like your PR, hope it will be merged!

Doc/library/datetime.rst

pganssle · 2019-05-21T03:44:38Z

I can read this more thoroughly a bit later, but I almost wonder if, considering it's a re-organization, if it would be good to get one or more reviews from someone who is not a domain expert in the datetime module. I imagine that e.g. @abalkin and I are not typical users of the datetime module.

Maybe @willingc or someone else with expertise in education?

Doc/library/datetime.rst

Carreau

Major improvement in readability for me.

Carreau · 2019-05-29T04:23:24Z

I can read this more thoroughly a bit later, but I almost wonder if, considering it's a re-organization, if it would be good to get one or more reviews from someone who is not a domain expert in the datetime module. I imagine that e.g. @abalkin and I are not typical users of the datetime module.

I don't think this is such a re-organisation, a couple of small paragraph have been placed in better suited location, but rarely too far from their original place. I think the impression is mostly due to git that can't really re-match some of the text with the original one.

bsolomon1124 · 2019-05-29T11:29:57Z

Many thanks for looking over this @Carreau - will make updates based on your suggestions soon.

willingc

Thanks for PR @bsolomon1124. It's a nice improvement. I've made a few suggestions to the changes. As an FYI for future large doc PRs, it makes the reviewer's task a bit easier when whitespace (one or two spaces after a period) is left as is. It's a bit quicker to skim through the content changes ☀️

Thanks also to the reviewers who have made comments too.

Doc/library/datetime.rst

bsolomon1124 · 2019-06-23T15:00:46Z

Thank you @willingc , I've incorporated all of your suggestions and will keep the whitespace tip in mind in future PRs.

willingc · 2019-06-23T17:28:39Z

Thanks @bsolomon1124 😄

@pganssle This looks good to me. If you want to give it a technical review as a datetime expert, that would be great.

bedevere-bot · 2019-07-06T03:03:11Z

Thanks for making the requested changes!

@pganssle, @willingc: please review the changes made to this pull request.

bsolomon1124 · 2019-07-29T01:18:13Z

Hey @pganssle, I know you've got plenty going on, but would love to have your eye on the remainder of this one. I think we are about 2/3 of the way through. Sorry to pester if you already had this on your radar.

pganssle · 2019-08-05T15:04:11Z

@bsolomon1124 Sorry, I will try to get to this as soon as I can. It was definitely on my radar as I'm very excited to get this merged, but Just reading a PR this large is very time-consuming, and I've got a pretty big backlog of things to review. Thanks for your patience.

pganssle

@bsolomon1124 Very nice work here, I have finished the review and I rebased your branch against master, cleaned up some of the merge conflicts and then pushed some new commits of my own.

I was able to use NORMALIZE_WHITESPACE to fix the linebreak issue: 85531ebd9f7c2ea8a3ba57a0fdd02a6616343d17
I did some minor rewording (I think this is just additional fixes, not anything related to your changes): 8ea5b4f70520b8ee26471de338f1e6ce58c9a907
I noticed that the paragraph about which formatting codes are supported was duplicated in two places, but neither of them seemed as good as putting it under the "Formatting codes" section, so I moved it there: 1c2803fca0914e24cea538fb60f7f7cae14a5c8c

Please let me know if you have any problems with my changes.

Note that because I did a rebase against the current master, you will need to do a force pull (or do a hard reset to the current head) before making additional changes. I think changes in the github interface will work fine, though.

Misc/NEWS.d/next/Documentation/2019-05-18-16-25-44.bpo-36960.xEKHXj.rst

bsolomon1124 · 2019-09-10T20:34:48Z

Looks awesome, thanks for rebasing and adding in your own changes @pganssle . I force pulled this branch from origin, made the html and did one more read-through, and I don't have any further edits at this point, good to go from my end.

Seriously appreciate your persistence here and have learned my lesson about making PRs more tightly-scoped in the future.

This is a restructuring of the datetime documentation to hopefully make them more user-friendly and approachable to new users without losing any of the detail. Changes include: - Creating dedicated subsections for some concepts such as: - "Constants" - "Naive vs Aware" - "Determining if an Object is Aware" - Give 'naive vs aware' its own subsection - Give 'constants' their own subsection - Overhauling the strftime-strptime section by: - Breaking it into logical, linkable, and digestable parts - Adding a high-level comparison table - Moving the technical detail to bottom: readers come to this section primarily to remind themselves to things: - How do I write the format code for X? - strptime/strftime: which one is which again? - Touching up fromisoformat + isoformat sections by: - Revising fromisoformat + isoformat for date, time, and datetime - Adding basic examples - Enforcing consistency about putting formats (i.e. ``HH:MM``) in double backticks. This was previously done in some places but not all - Putting long 'supported formats', on their own line to improve readability - Moving the 'seealso' section to the top and add a link to dateutil Rationale: This doesn't really belong nested under the 'constants' section. Let readers know right away that datetime is one of several related tools. - Moving common features of several types into one place: Previously, each type went out of its way to note separately that it was hashable and picklable. These can be brought into one single place that is more prominent. - Reducing some verbose explanations to improve readability - Breaking up long paragraphs into digestable chunks - Displaying longer "equivalent to" examples, as short code blocks - Using the dot notation for datetime/time classes: Use :class:`.time` and :class:`.datetime` rather than :class:`time` and :class:`datetime`; otherwise, the generated links will route to the respective modules, not classes. - Rewording the tzinfo class description The top paragraph should get straight to the point of telling the reader what subclasses of tzinfo _do_. Previously, that was hidden in a later paragraph. - Adding a note on .today() versus .now() - Rearranging and expanding example blocks, including: - Moved long, multiline inline examples to standalone examples - Simplified the example block for timedelta arithmetic: - Broke the example into two logical sections: 1. normalization/parameter 'merging' 2. timedelta arithmetic - Reduced the complexity of the some of the examples. Show reasonable, real-world uses cases that are easy to follow along with and progres in difficult slightly. - Broke up the example sections for date and datetime sections by putting the easy examples first, progressing to more esoteric situations and breaking it up into logical sections based on what the methods are doing at a high level. - Simplified the KabulTz example: - Put the class definition itself into a non-REPL block since there is no interactive output involved there - Briefly explained what's happening before launching into the code - Broke the example section into visually separate chunks - Various whitespace, formatting, style and grammar fixes including: - Consistently using backctics for 'date_string' formats - Consistently using one space after periods. - Consistently using bold for vocab terms - Consistently using italics when referring to params: See https://devguide.python.org/documenting/#id4 - Using '::' to lead into code blocks Per https://devguide.python.org/documenting/#source-code, this will let the reader use the 'expand/collapse' top-right button for REPL blocks to hide or show the prompt. - Using consistent captialization schemes - Removing use of the default role - Put 'example' blocks in Markdown subsections This is a combination of 66 commits. See bpo-36960: https://bugs.python.org/issue36960

pganssle · 2019-09-11T09:24:19Z

Got this all squashed down and hopefully captured your excellently worded atomic commit messages in the combined commit message. This was one of those situations where I was pretty sad that we can only do squash merges for CPython, because it wouldn't have been too much work to do an interactive rebase and make this about 45 individual atomic commits.

🎉 Beautiful work, @bsolomon1124! 🎉

By the way, with regards to this:

Seriously appreciate your persistence here and have learned my lesson about making PRs more tightly-scoped in the future.

Please do not let the long delay in review prevent you from making ambitious changes in the future if they are warranted. This PR could have probably been broken up into a number of smaller PRs that would have been easier to merge, but this didn't have nearly the scope creep that some PRs get. Thank you for taking the time to do such a great job on this, I hope it will make things much easier for new users of datetime.

miss-islington · 2019-09-12T14:22:30Z

Thanks @bsolomon1124 for the PR, and @pganssle for merging it 🌮🎉.. I'm working now to backport this PR to: 3.8.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

This is a restructuring of the datetime documentation to hopefully make them more user-friendly and approachable to new users without losing any of the detail. Changes include: - Creating dedicated subsections for some concepts such as: - "Constants" - "Naive vs Aware" - "Determining if an Object is Aware" - Give 'naive vs aware' its own subsection - Give 'constants' their own subsection - Overhauling the strftime-strptime section by: - Breaking it into logical, linkable, and digestable parts - Adding a high-level comparison table - Moving the technical detail to bottom: readers come to this section primarily to remind themselves to things: - How do I write the format code for X? - strptime/strftime: which one is which again? - Touching up fromisoformat + isoformat sections by: - Revising fromisoformat + isoformat for date, time, and datetime - Adding basic examples - Enforcing consistency about putting formats (i.e. ``HH:MM``) in double backticks. This was previously done in some places but not all - Putting long 'supported formats', on their own line to improve readability - Moving the 'seealso' section to the top and add a link to dateutil Rationale: This doesn't really belong nested under the 'constants' section. Let readers know right away that datetime is one of several related tools. - Moving common features of several types into one place: Previously, each type went out of its way to note separately that it was hashable and picklable. These can be brought into one single place that is more prominent. - Reducing some verbose explanations to improve readability - Breaking up long paragraphs into digestable chunks - Displaying longer "equivalent to" examples, as short code blocks - Using the dot notation for datetime/time classes: Use :class:`.time` and :class:`.datetime` rather than :class:`time` and :class:`datetime`; otherwise, the generated links will route to the respective modules, not classes. - Rewording the tzinfo class description The top paragraph should get straight to the point of telling the reader what subclasses of tzinfo _do_. Previously, that was hidden in a later paragraph. - Adding a note on .today() versus .now() - Rearranging and expanding example blocks, including: - Moved long, multiline inline examples to standalone examples - Simplified the example block for timedelta arithmetic: - Broke the example into two logical sections: 1. normalization/parameter 'merging' 2. timedelta arithmetic - Reduced the complexity of the some of the examples. Show reasonable, real-world uses cases that are easy to follow along with and progres in difficult slightly. - Broke up the example sections for date and datetime sections by putting the easy examples first, progressing to more esoteric situations and breaking it up into logical sections based on what the methods are doing at a high level. - Simplified the KabulTz example: - Put the class definition itself into a non-REPL block since there is no interactive output involved there - Briefly explained what's happening before launching into the code - Broke the example section into visually separate chunks - Various whitespace, formatting, style and grammar fixes including: - Consistently using backctics for 'date_string' formats - Consistently using one space after periods. - Consistently using bold for vocab terms - Consistently using italics when referring to params: See https://devguide.python.org/documenting/GH-id4 - Using '::' to lead into code blocks Per https://devguide.python.org/documenting/GH-source-code, this will let the reader use the 'expand/collapse' top-right button for REPL blocks to hide or show the prompt. - Using consistent captialization schemes - Removing use of the default role - Put 'example' blocks in Markdown subsections This is a combination of 66 commits. See bpo-36960: https://bugs.python.org/issue36960 (cherry picked from commit 3fb1363) Co-authored-by: Brad <[email protected]>

bedevere-bot · 2019-09-12T14:22:38Z

GH-16056 is a backport of this pull request to the 3.8 branch.

pganssle · 2019-09-12T14:23:13Z

I'm going to go ahead and backport this to 3.8, partially because it would be nice to get the changes in for the upcoming version and partially because it will make backporting all documentation fixes a total pain if it doesn't get backported 😛

This is a restructuring of the datetime documentation to hopefully make them more user-friendly and approachable to new users without losing any of the detail. Changes include: - Creating dedicated subsections for some concepts such as: - "Constants" - "Naive vs Aware" - "Determining if an Object is Aware" - Give 'naive vs aware' its own subsection - Give 'constants' their own subsection - Overhauling the strftime-strptime section by: - Breaking it into logical, linkable, and digestable parts - Adding a high-level comparison table - Moving the technical detail to bottom: readers come to this section primarily to remind themselves to things: - How do I write the format code for X? - strptime/strftime: which one is which again? - Touching up fromisoformat + isoformat sections by: - Revising fromisoformat + isoformat for date, time, and datetime - Adding basic examples - Enforcing consistency about putting formats (i.e. ``HH:MM``) in double backticks. This was previously done in some places but not all - Putting long 'supported formats', on their own line to improve readability - Moving the 'seealso' section to the top and add a link to dateutil Rationale: This doesn't really belong nested under the 'constants' section. Let readers know right away that datetime is one of several related tools. - Moving common features of several types into one place: Previously, each type went out of its way to note separately that it was hashable and picklable. These can be brought into one single place that is more prominent. - Reducing some verbose explanations to improve readability - Breaking up long paragraphs into digestable chunks - Displaying longer "equivalent to" examples, as short code blocks - Using the dot notation for datetime/time classes: Use :class:`.time` and :class:`.datetime` rather than :class:`time` and :class:`datetime`; otherwise, the generated links will route to the respective modules, not classes. - Rewording the tzinfo class description The top paragraph should get straight to the point of telling the reader what subclasses of tzinfo _do_. Previously, that was hidden in a later paragraph. - Adding a note on .today() versus .now() - Rearranging and expanding example blocks, including: - Moved long, multiline inline examples to standalone examples - Simplified the example block for timedelta arithmetic: - Broke the example into two logical sections: 1. normalization/parameter 'merging' 2. timedelta arithmetic - Reduced the complexity of the some of the examples. Show reasonable, real-world uses cases that are easy to follow along with and progres in difficult slightly. - Broke up the example sections for date and datetime sections by putting the easy examples first, progressing to more esoteric situations and breaking it up into logical sections based on what the methods are doing at a high level. - Simplified the KabulTz example: - Put the class definition itself into a non-REPL block since there is no interactive output involved there - Briefly explained what's happening before launching into the code - Broke the example section into visually separate chunks - Various whitespace, formatting, style and grammar fixes including: - Consistently using backctics for 'date_string' formats - Consistently using one space after periods. - Consistently using bold for vocab terms - Consistently using italics when referring to params: See https://devguide.python.org/documenting/GH-id4 - Using '::' to lead into code blocks Per https://devguide.python.org/documenting/GH-source-code, this will let the reader use the 'expand/collapse' top-right button for REPL blocks to hide or show the prompt. - Using consistent captialization schemes - Removing use of the default role - Put 'example' blocks in Markdown subsections This is a combination of 66 commits. See bpo-36960: https://bugs.python.org/issue36960 (cherry picked from commit 3fb1363) Co-authored-by: Brad <[email protected]>

This is a restructuring of the datetime documentation to hopefully make them more user-friendly and approachable to new users without losing any of the detail. Changes include: - Creating dedicated subsections for some concepts such as: - "Constants" - "Naive vs Aware" - "Determining if an Object is Aware" - Give 'naive vs aware' its own subsection - Give 'constants' their own subsection - Overhauling the strftime-strptime section by: - Breaking it into logical, linkable, and digestable parts - Adding a high-level comparison table - Moving the technical detail to bottom: readers come to this section primarily to remind themselves to things: - How do I write the format code for X? - strptime/strftime: which one is which again? - Touching up fromisoformat + isoformat sections by: - Revising fromisoformat + isoformat for date, time, and datetime - Adding basic examples - Enforcing consistency about putting formats (i.e. ``HH:MM``) in double backticks. This was previously done in some places but not all - Putting long 'supported formats', on their own line to improve readability - Moving the 'seealso' section to the top and add a link to dateutil Rationale: This doesn't really belong nested under the 'constants' section. Let readers know right away that datetime is one of several related tools. - Moving common features of several types into one place: Previously, each type went out of its way to note separately that it was hashable and picklable. These can be brought into one single place that is more prominent. - Reducing some verbose explanations to improve readability - Breaking up long paragraphs into digestable chunks - Displaying longer "equivalent to" examples, as short code blocks - Using the dot notation for datetime/time classes: Use :class:`.time` and :class:`.datetime` rather than :class:`time` and :class:`datetime`; otherwise, the generated links will route to the respective modules, not classes. - Rewording the tzinfo class description The top paragraph should get straight to the point of telling the reader what subclasses of tzinfo _do_. Previously, that was hidden in a later paragraph. - Adding a note on .today() versus .now() - Rearranging and expanding example blocks, including: - Moved long, multiline inline examples to standalone examples - Simplified the example block for timedelta arithmetic: - Broke the example into two logical sections: 1. normalization/parameter 'merging' 2. timedelta arithmetic - Reduced the complexity of the some of the examples. Show reasonable, real-world uses cases that are easy to follow along with and progres in difficult slightly. - Broke up the example sections for date and datetime sections by putting the easy examples first, progressing to more esoteric situations and breaking it up into logical sections based on what the methods are doing at a high level. - Simplified the KabulTz example: - Put the class definition itself into a non-REPL block since there is no interactive output involved there - Briefly explained what's happening before launching into the code - Broke the example section into visually separate chunks - Various whitespace, formatting, style and grammar fixes including: - Consistently using backctics for 'date_string' formats - Consistently using one space after periods. - Consistently using bold for vocab terms - Consistently using italics when referring to params: See https://devguide.python.org/documenting/#id4 - Using '::' to lead into code blocks Per https://devguide.python.org/documenting/#source-code, this will let the reader use the 'expand/collapse' top-right button for REPL blocks to hide or show the prompt. - Using consistent captialization schemes - Removing use of the default role - Put 'example' blocks in Markdown subsections This is a combination of 66 commits. See bpo-36960: https://bugs.python.org/issue36960

the-knights-who-say-ni added the CLA signed label May 18, 2019

bedevere-bot added docs Documentation in the Doc dir awaiting review labels May 18, 2019

bsolomon1124 changed the title ~~Make datetime docs more user-friendly~~ bpo-36960: Make datetime docs more user-friendly May 18, 2019

csabella requested a review from abalkin May 18, 2019 20:23

alessandrocucci reviewed May 18, 2019

View reviewed changes

bsolomon1124 force-pushed the datetime-user-friendly-docs branch from f9b80a4 to 057df4b Compare May 18, 2019 21:14

willingc self-requested a review May 21, 2019 11:40