René's URL Explorer Experiment

Title: [3.8] bpo-36960: Overhaul datetime documentation (GH-13410) by miss-islington · Pull Request #16056 · python/cpython · GitHub

Open Graph Title: [3.8] bpo-36960: Overhaul datetime documentation (GH-13410) by miss-islington · Pull Request #16056 · python/cpython

X Title: [3.8] bpo-36960: Overhaul datetime documentation (GH-13410) by miss-islington · Pull Request #16056 · python/cpython

Description: 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: normalization/parameter 'merging' 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

Open Graph Description: 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 ...

X Description: 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 ...

Opengraph URL: https://github.com/python/cpython/pull/16056

X: @github

direct link

Domain: github.com

Links:

Viewport: width=device-width