GeezerVison

Copy link

Copy Markdown

Contributor

alessandrocucci and pganssle reacted with thumbs up emoji GPHemsley reacted with heart emoji

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

alessandrocucci reviewed May 18, 2019

View reviewed changes

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

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

Carreau reviewed May 29, 2019

View reviewed changes

Carreau reviewed May 29, 2019

View reviewed changes

Carreau reviewed May 29, 2019

View reviewed changes

Carreau reviewed May 29, 2019

View reviewed changes

Carreau reviewed May 29, 2019

View reviewed changes

Carreau reviewed May 29, 2019

View reviewed changes

Carreau approved these changes May 29, 2019

View reviewed changes

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

bsolomon1124 requested a review from pganssle as a code owner June 22, 2019 17:22

willingc reviewed Jun 23, 2019

View reviewed changes

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

willingc approved these changes Jun 23, 2019

View reviewed changes

pganssle requested changes Jul 2, 2019

View reviewed changes

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

pganssle approved these changes Sep 10, 2019

View reviewed changes

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

pganssle removed the request for review from abalkin September 11, 2019 09:16

bsolomon1124 deleted the datetime-user-friendly-docs branch September 11, 2019 11:12

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/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