bpo-36960: Make datetime docs more user-friendly by bsolomon1124 · Pull Request #13410 · python/cpython (original) (raw)

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Conversation80 Commits1 Checks0 Files changed

Conversation

This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters

[ Show hidden characters]({{ revealButtonHref }})

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.

bsolomon1124 changed the titleMake datetime docs more user-friendly bpo-36960: Make datetime docs more user-friendly

May 18, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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?

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Major improvement in readability for me.

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.

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

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

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.

Thanks for making the requested changes!

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

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.

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

1. I was able to use NORMALIZE_WHITESPACE to fix the linebreak issue: 85531ebd9f7c2ea8a3ba57a0fdd02a6616343d17
2. I did some minor rewording (I think this is just additional fixes, not anything related to your changes): 8ea5b4f70520b8ee26471de338f1e6ce58c9a907
3. 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.

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

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.

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!

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request

Sep 12, 2019

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 brad.solomon.1124@gmail.com

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 😛

miss-islington added a commit that referenced this pull request

Sep 12, 2019

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 brad.solomon.1124@gmail.com

websurfer5 pushed a commit to websurfer5/cpython that referenced this pull request

Jul 20, 2020

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

Labels

docs

Documentation in the Doc dir