Skip to content

Wrong/missing code formats in datetime documentation #85453

Closed as duplicate

Description

@yyyyyyyan
mannequin
BPO 41281
Nosy @ezio-melotti, @merwok, @willingc, @JulienPalard, @yyyyyyyan
PRs
  • gh-85453: Fix missing/wrong backquotes and role texts in datetime documentation #21447
  • Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.

    Show more details

    GitHub fields:

    assignee = None
    closed_at = None
    created_at = <Date 2020-07-12.05:26:29.849>
    labels = ['type-feature', '3.8', '3.9', '3.10', 'docs']
    title = 'Wrong/missing code formats in datetime documentation'
    updated_at = <Date 2020-07-12.05:29:56.710>
    user = 'https://github.com/yyyyyyyan'

    bugs.python.org fields:

    activity = <Date 2020-07-12.05:29:56.710>
    actor = 'yyyyyyyan'
    assignee = 'docs@python'
    closed = False
    closed_date = None
    closer = None
    components = ['Documentation']
    creation = <Date 2020-07-12.05:26:29.849>
    creator = 'yyyyyyyan'
    dependencies = []
    files = []
    hgrepos = []
    issue_num = 41281
    keywords = ['patch']
    message_count = 1.0
    messages = ['373547']
    nosy_count = 6.0
    nosy_names = ['ezio.melotti', 'eric.araujo', 'docs@python', 'willingc', 'mdk', 'yyyyyyyan']
    pr_nums = ['21447']
    priority = 'normal'
    resolution = None
    stage = 'patch review'
    status = 'open'
    superseder = None
    type = 'enhancement'
    url = 'https://bugs.python.org/issue41281'
    versions = ['Python 3.8', 'Python 3.9', 'Python 3.10']

    Linked PRs

    Activity

    1. uatach commented on Apr 18, 2024

      @uatach
      Contributor

      hello @erlend-aasland, I would like to help with this

    2. erlend-aasland commented on Apr 18, 2024

      @erlend-aasland
      Contributor

      Great, @uatach, go ahead! Let me know if you have any questions.

    3. erlend-aasland commented on Apr 24, 2024

      @erlend-aasland
      Contributor

      In PR #118068, code formatting was removed from many numeric literals; let's follow up with a PR to make that consistent across datetime.rst. The following lines still contain numeric literals marked up with double backticks:

      • L94
      • L2564
      • L2711
    4. erlend-aasland commented on Apr 24, 2024

      @erlend-aasland
      Contributor

      Remark by Serhiy #118068 (comment) for L373:

      I understand what it means, but it would be nice to explain what does "zero" mean. Is it already explained anywhere?

      Division by zero raises :exc:`ZeroDivisionError`.

    5. erlend-aasland commented on Apr 24, 2024

      @erlend-aasland
      Contributor

      Remark by Serhiy #118068 (comment):

      Should not the sentence start with the title case?

      | ``-t1`` | equivalent to ``timedelta(-t1.days, |
      | | -t1.seconds*, -t1.microseconds)``, |
      | | and to ``t1 * -1``. (1)(4) |
      +--------------------------------+-----------------------------------------------+
      | ``abs(t)`` | equivalent to ``+t`` when ``t.days >= 0``, |
      | | and to ``-t`` when ``t.days < 0``. (2) |

      Check the whole file and fix up any incorrect capitalisation.

    6. erlend-aasland commented on Apr 24, 2024

      @erlend-aasland
      Contributor

      Remark by Serhiy #118068 (comment):

      Needed a reference to (3).

      | ``t1 = t2 / f or t1 = t2 / i`` | Delta divided by a float or an int. The result|
      | | is rounded to the nearest multiple of |
      | | timedelta.resolution using round-half-to-even.|

    7. added a commit that references this issue on Apr 24, 2024
    8. added a commit that references this issue on Apr 24, 2024
    9. added 2 commits that reference this issue on Apr 24, 2024
    10. added a commit that references this issue on Apr 24, 2024
    11. added a commit that references this issue on Apr 24, 2024
    12. hugovk commented on Apr 24, 2024

      @hugovk
      Member

      Remark by Serhiy #118068 (comment) for L373:

      I understand what it means, but it would be nice to explain what does "zero" mean. Is it already explained anywhere?

      Division by zero raises :exc:`ZeroDivisionError`.

      I'm not sure if we need to define zero = 0 = nothing?

    13. uatach commented on Apr 25, 2024

      @uatach
      Contributor

      Just to make sure about the remaining changes from the old closed PR:

      @erlend-aasland I could list these as remaining, not sure if they are all still relevant or if I missed anything

    14. erlend-aasland commented on Apr 25, 2024

      @erlend-aasland
      Contributor
      • There was a change related to None, most occurrences use backquotes but on L1738, there's a :const:None and, on L2490, there's a None without backquotes

      We've been fixing up these from time to time, so there is precedent to create a PR to consistently mark up None using double backquotes throughout datetime.rst.

      • There were changes related to standardize "timezone" as "time zone"
        [...]
      • There was a change from local datetime to local date and time on L872

      I'd audit the whole file and collect all spelling issues in a single PR. Making sure the language in the reference is correct, aligns with the Diátaxis principles.

      • There were changes related to italics, like the q and r on L341

      Those should be marked up as variables using double backticks.

      Moreover, all method and function parameters should be marked up in italics.

      • There were a lot of changes related to :class:.timezone, :class:.tzinfo and others

      We should make sure all these links work as expected; I'd do an audit of all of them and fix any incorrect links. Also, for each reference we should make sure there's not more than one link per paragraph; that is: if tzinfo is referenced twice in a paragraph, only create a link for the first reference.

    15. serhiy-storchaka commented on Apr 25, 2024

      @serhiy-storchaka
      Member

      I added a note about "Division by zero" because "zero" here is not only 0, but a timedelta with zero duration. Is it defined as "zero" anywhere? This value is special, because it is the only timedelta value with false boolean value.

      There is also confusing line across one of tables. Either it should be removed, or the cells below it are misplaced.

    16. added a commit that references this issue on Apr 30, 2024
    17. added a commit that references this issue on Apr 30, 2024
    18. added a commit that references this issue on Apr 30, 2024
    19. added 2 commits that reference this issue on May 8, 2024
    20. ayushman2046 commented on Jul 9, 2024

      @ayushman2046

      Is this issue still open? I would like to contribute.

    21. merwok commented on Jul 9, 2024

      @merwok
      Member

      Could the docs editorial board review this?

      I am not convinced of the necessity of avoiding timezone or datetime.
      Timezone, like filesystem, is a form with a special meaning, now common in normal English to represent the concept.
      Things like the current datetime are not common, but they are readily understandable in the context of the python datetime module docs.

    22. willingc commented on Jul 12, 2024

      @willingc
      Contributor

      @python/editorial-board Please review thoughts on moving from timezone in prose docs to time zone. I'm leaning toward @merwok's perspective that the change is not a necessity. Looking for additional perspective on this.

    23. gvanrossum commented on Jul 12, 2024

      @gvanrossum
      Member

      @python/editorial-board Please review thoughts on moving from timezone in prose docs to time zone. I'm leaning toward @merwok's perspective that the change is not a necessity. Looking for additional perspective on this.

      There are already plenty of places where the docs use "time zone" (when referring to the general concept, not the module or object). I Googled and the consensus seems to be that it's two words.

      Regarding "datetime" vs. "date time", neither is correct English. IMO the concept ought to be referred to as "date and time", or could possibly shortened as "date/time". But I'm more open to keeping "datetime" as a form of jargon we're inventing. (Though I don't feel that way about "timezone".)

    24. erlend-aasland commented on Jul 12, 2024

      @erlend-aasland
      Contributor

      IMO the concept ought to be referred to as "date and time", [...]

      Yes, this is what #118449 proposes.

    25. added a commit that references this issue on Jul 16, 2024
    26. added 2 commits that reference this issue on Jul 16, 2024
    27. added a commit that references this issue on Jul 16, 2024
    28. added a commit that references this issue on Jul 17, 2024
    29. added a commit that references this issue on Jul 23, 2024
    30. added a commit that references this issue on Sep 5, 2024
    31. added 2 commits that reference this issue on Sep 5, 2024
    32. added 2 commits that reference this issue on Sep 5, 2024
    33. added a commit that references this issue on Oct 14, 2024
    34. added 2 commits that reference this issue on Oct 14, 2024
    35. added 2 commits that reference this issue on Oct 14, 2024
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

    Metadata

    Metadata

    Assignees

    No one assigned

      Labels

      docsDocumentation in the Doc direasytype-featureA feature request or enhancement

      Projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions