[issue17701] Improving strftime documentation
New submission from David Wolever: The current strftime documentation isn't very helpful. It doesn't have examples, and the ordering is unhelpful. I've also moved some format-specific notes into the notes below the format-string-table, because the format string table is what 98%* of people care about. TODO before this can be merged: - Clean up note order - Check that it works with the Python 3 docs *: based on a sample size of 1 ---------- assignee: docs@python components: Documentation files: strftime-docs.diff keywords: needs review, patch messages: 186601 nosy: docs@python, wolever priority: normal severity: normal status: open title: Improving strftime documentation type: enhancement versions: Python 2.7 Added file: http://bugs.python.org/file29784/strftime-docs.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
Changes by Alex Gaynor <alex.gaynor@gmail.com>: ---------- nosy: +alex _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
Éric Araujo added the comment: Thanks for the patch, looks good. I’d put the versionadded block at the end of the note rather than the beginning, to match usual conventions. ---------- nosy: +eric.araujo stage: -> patch review versions: +Python 3.3, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
Changes by David Wolever <wolever@cs.toronto.edu>: Added file: http://bugs.python.org/file29785/strftime-docs.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
David Wolever added the comment: Ah, yes — thanks Éric. I've fiddled with the wording on the %f note a bit so it makes more sense along with the versionadded, and removed the versionadded text, which is basically identical to the note and description. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
Changes by David Wolever <wolever@cs.toronto.edu>: ---------- hgrepos: +182 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
Changes by David Wolever <wolever@cs.toronto.edu>: Added file: http://bugs.python.org/file29836/b3b1dcdc8cee.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
Changes by David Wolever <wolever@cs.toronto.edu>: Removed file: http://bugs.python.org/file29836/b3b1dcdc8cee.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
Changes by David Wolever <wolever@cs.toronto.edu>: Added file: http://bugs.python.org/file29839/ae18c5ae2c4d.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
David Wolever added the comment: Ok, I've added some locale examples and fixed up the note numbering. See diff in file29839, and there is a live version to preview here: http://hul.wolever.net/python-doc/library/datetime.html#strftime-and-strptim... If I can get a +1 on this, I'll port it to Python 3. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
Changes by David Wolever <wolever@cs.toronto.edu>: Added file: http://bugs.python.org/file29841/53a0e908f787.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
David Wolever added the comment: Fixed a misleading note about Unicode in localized formatters in file29841. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
Changes by David Wolever <wolever@cs.toronto.edu>: Added file: http://bugs.python.org/file30353/102b3e257dca.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
Changes by David Wolever <wolever@cs.toronto.edu>: Removed file: http://bugs.python.org/file30353/102b3e257dca.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
Changes by David Wolever <wolever@cs.toronto.edu>: Added file: http://bugs.python.org/file30354/0f4d971b0cee.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
Éric Araujo added the comment: Looks good. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
Roundup Robot added the comment: New changeset adbc9789a5e4 by David Wolever in branch '2.7': Issue #17701: Improving strftime documentation http://hg.python.org/cpython/rev/adbc9789a5e4 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
Roundup Robot added the comment: New changeset 1d4b02d8fa8a by David Wolever in branch '3.3': Issue #17701: Improving strftime documentation. http://hg.python.org/cpython/rev/1d4b02d8fa8a New changeset ab550dac6209 by David Wolever in branch 'default': Merge issue #17701: Improving strftime documentation. http://hg.python.org/cpython/rev/ab550dac6209 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
David Wolever added the comment: Done, pushed to 2.7, 3.3, default. ---------- resolution: -> fixed status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
Changes by Alex Gaynor <alex.gaynor@gmail.com>: ---------- nosy: +alex _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
Éric Araujo added the comment: Thanks for the patch, looks good. I’d put the versionadded block at the end of the note rather than the beginning, to match usual conventions. ---------- nosy: +eric.araujo stage: -> patch review versions: +Python 3.3, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
Changes by David Wolever <wolever@cs.toronto.edu>: Added file: http://bugs.python.org/file29785/strftime-docs.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
David Wolever added the comment: Ah, yes — thanks Éric. I've fiddled with the wording on the %f note a bit so it makes more sense along with the versionadded, and removed the versionadded text, which is basically identical to the note and description. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
Changes by David Wolever <wolever@cs.toronto.edu>: ---------- hgrepos: +182 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
Changes by David Wolever <wolever@cs.toronto.edu>: Added file: http://bugs.python.org/file29836/b3b1dcdc8cee.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
Changes by David Wolever <wolever@cs.toronto.edu>: Removed file: http://bugs.python.org/file29836/b3b1dcdc8cee.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
Changes by David Wolever <wolever@cs.toronto.edu>: Added file: http://bugs.python.org/file29839/ae18c5ae2c4d.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
David Wolever added the comment: Ok, I've added some locale examples and fixed up the note numbering. See diff in file29839, and there is a live version to preview here: http://hul.wolever.net/python-doc/library/datetime.html#strftime-and-strptim... If I can get a +1 on this, I'll port it to Python 3. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
Changes by David Wolever <wolever@cs.toronto.edu>: Added file: http://bugs.python.org/file29841/53a0e908f787.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
David Wolever added the comment: Fixed a misleading note about Unicode in localized formatters in file29841. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
Changes by David Wolever <wolever@cs.toronto.edu>: Added file: http://bugs.python.org/file30353/102b3e257dca.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
Changes by David Wolever <wolever@cs.toronto.edu>: Removed file: http://bugs.python.org/file30353/102b3e257dca.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
Changes by David Wolever <wolever@cs.toronto.edu>: Added file: http://bugs.python.org/file30354/0f4d971b0cee.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
Éric Araujo added the comment: Looks good. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
Roundup Robot added the comment: New changeset adbc9789a5e4 by David Wolever in branch '2.7': Issue #17701: Improving strftime documentation http://hg.python.org/cpython/rev/adbc9789a5e4 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
Roundup Robot added the comment: New changeset 1d4b02d8fa8a by David Wolever in branch '3.3': Issue #17701: Improving strftime documentation. http://hg.python.org/cpython/rev/1d4b02d8fa8a New changeset ab550dac6209 by David Wolever in branch 'default': Merge issue #17701: Improving strftime documentation. http://hg.python.org/cpython/rev/ab550dac6209 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
David Wolever added the comment: Done, pushed to 2.7, 3.3, default. ---------- resolution: -> fixed status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________
participants (4)
-
Alex Gaynor -
David Wolever
-
Roundup Robot
-
Éric Araujo