[issue16154] Some minor doc fixes in Doc/library
New submission from Ravi Sinha: - Doc/library/math.rst - fsum will pass if 'from math import fsum' is done before it, but I've left such issues for now since there seems to be a debate about how to go about that - some seem unfixable too - e.g. Doc/library/filecmp.rst - 'dir1' and 'dir2' do not exist, and so the print_diff_files() fails, but there seems to be no reason to fix this; the same for Doc/library/imghdr.rst - there is no /tmp/bass.gif, so it fails - some fail for inexplicable reasons - Doc/library/string.rst - the table of numbers does not match, though it is exactly the same. No idea why. ---------- assignee: docs@python components: Documentation files: doc_lib.patch keywords: patch messages: 172253 nosy: Ravi.Sinha, chris.jerdonek, docs@python, r.david.murray, terry.reedy priority: normal severity: normal status: open title: Some minor doc fixes in Doc/library type: enhancement versions: Python 3.4 Added file: http://bugs.python.org/file27462/doc_lib.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Chris Jerdonek added the comment:
fsum will pass if 'from math import fsum' is done before it, but I've left such issues for now since there seems to be a debate about how to go about that
For now, you can at least use the "testsetup" directive which will simultaneously allow the doctests to pass but cause the subsequent lines to be hidden in the rendered HTML. We can always remove the directive at a later date to cause it to display. See here for an example: http://bugs.python.org/review/15888/diff/6011/Doc/howto/ipaddress.rst
- some seem unfixable too
Can you include links to the questionable areas for examples like these (e.g. using the "browse source" page http://hg.python.org/cpython/file/default/ )? This will make it easier to reference and discuss. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Terry J. Reedy added the comment: I consider some items to be errors. In any case, all current docs can be fixed. First, your questions as to what you did not fix. fsum: I personally would add the import visibly, but at least add it hidden, as Chris suggested. 171 >>> from filecmp import dircmp 172 >>> def print_diff_files(dcmp): 173 ... for name in dcmp.diff_files: 174 ... print("diff_file %s found in %s and %s" % (name, dcmp.left, 175 ... dcmp.right)) 176 ... for sub_dcmp in dcmp.subdirs.values(): 177 ... print_diff_files(sub_dcmp) 178 ... 179 >>> dcmp = dircmp('dir1', 'dir2') 180 >>> print_diff_files(dcmp) (copying from the repository view deletes whitespace) The import and def should run and should be tested. The last 2 lines should not be tested: add #doctest: SKIP to both. (I gather that Sphinx will strip this.)
I believe the problem here is the "end = ''" part. It puts a blank space at the end of each line, which got deleted when I pasted the above, which was cut from my local repository. Trailing blanks are *really* a problem and code that produces them is not a good example. I suggest changing width to 6, end to '', and adding '' to the beginning of each output line. It should then pass. ---------- type: enhancement -> behavior versions: +Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Chris Jerdonek added the comment:
Trailing blanks are *really* a problem
The NORMALIZE_WHITESPACE doctest directive is another option to deal with cases like these. It ignores whitespace-only differences between the actual and expected outputs. Does it pass with that directive? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Terry J. Reedy added the comment: Now your patch: colorsys: same change all versions fractions: ditto Template: ditto I believe the changes I suggested for filecmp and the numbers should also be the same in all versions. ACKS: your name should be inserted in alpha order ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Terry J. Reedy added the comment: I considered the directive, but I mildly prefer the code change. end = ' ') guarantees a blank between fields even if one formats a too-large number end = '') does not add a blank to the end. end = '' if base == 'b' else ' ') does both (but depends on having a 'last field' condition. I actual practice, I might use the third option. However, if you do the commit, it is your choice. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Chris Jerdonek added the comment:
I considered the directive, but I mildly prefer the code change.
I just wanted to point the directive out as an available option (especially for Ravi if he does further patches like this). Either way is fine with me. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Terry J. Reedy added the comment: Apparently, I should have suggested "# doctest: +SKIP". The #12947 fix to example directives being deleted from the directive examples came after the 3.3.0 release. Fixed examples are at http://docs.python.org/py3k/library/doctest.html#option-flags-and-directives ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Ravi Sinha added the comment: I've used the testsetup directive and the problem in http://hg.python.org/cpython/file/40a1652349e9/Doc/library/math.rst, line 79, is fixed; the test passes Added # doctest: +SKIP to lines 179 and 180 in http://hg.python.org/cpython/file/40a1652349e9/Doc/library/filecmp.rst, and it passes too For http://hg.python.org/cpython/file/40a1652349e9/Doc/library/string.rst, lines 612-624, used +NORMALIZE_WHITESPACE and the test passed, but since Terry preferred a code change, did that too; the test passes Put my name at the proper position in Misc/ACKS For the multiple versions, I needed to ask whether they'd all belong to this same patch or there would be different patches for each version? Sorry if it's a silly question; I haven't had the time to wrap my head around how to best work with all the versions together With the directives Chris and Terry suggested, it should be easy to make several other tests pass; I'll make a few more patches ---------- Added file: http://bugs.python.org/file27574/doc_lib_Oct14_2012.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Changes by Ravi Sinha <rss1406@gmail.com>: Added file: http://bugs.python.org/file27649/27.doc_lib_Oct21_2012.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Changes by Ravi Sinha <rss1406@gmail.com>: Added file: http://bugs.python.org/file27650/32.doc_lib_Oct21_2012.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Changes by Ravi Sinha <rss1406@gmail.com>: Added file: http://bugs.python.org/file27651/33.doc_lib_Oct21_2012.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Ravi Sinha added the comment: Based on what I saw on some other issues, I think there is just a separate patch for each version (coming from separate working repositories), but all attached to the same issue. So I am doing the same. All the changes have been made to files under Doc/library/ - colorsys.rst, filecmp.rst, fractions.rst, math.rst, string.rst and Misc/ACKS. The beginning number for each patch and the description show which version it's meant for. There are some minor differences for 2.7 and 3.2; they either did not need a fix or needed some more tests to be skipped. For 2.7 and 3.2 I don't know how to use the online source browser to link the files directly. Please let me know if the patches are okay or how to go from here. Thanks. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ezio.melotti stage: -> patch review _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Roundup Robot added the comment: New changeset 9b3d0bdb9256 by Ezio Melotti in branch '2.7': #16154: fix some doctests in Doc/library. Patch by Ravi Sinha. http://hg.python.org/cpython/rev/9b3d0bdb9256 New changeset 5b405df8518d by Ezio Melotti in branch '3.2': #16154: fix some doctests in Doc/library. Patch by Ravi Sinha. http://hg.python.org/cpython/rev/5b405df8518d New changeset 3e884b3804b3 by Ezio Melotti in branch '3.3': #16154: merge with 3.2. http://hg.python.org/cpython/rev/3e884b3804b3 New changeset 5ec8daab477a by Ezio Melotti in branch 'default': #16154: merge with 3.3. http://hg.python.org/cpython/rev/5ec8daab477a ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Ezio Melotti added the comment: Fixed, thanks for the report and the patch! ---------- assignee: docs@python -> ezio.melotti resolution: -> fixed stage: patch review -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Chris Jerdonek added the comment:
fsum will pass if 'from math import fsum' is done before it, but I've left such issues for now since there seems to be a debate about how to go about that
For now, you can at least use the "testsetup" directive which will simultaneously allow the doctests to pass but cause the subsequent lines to be hidden in the rendered HTML. We can always remove the directive at a later date to cause it to display. See here for an example: http://bugs.python.org/review/15888/diff/6011/Doc/howto/ipaddress.rst
- some seem unfixable too
Can you include links to the questionable areas for examples like these (e.g. using the "browse source" page http://hg.python.org/cpython/file/default/ )? This will make it easier to reference and discuss. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Terry J. Reedy added the comment: I consider some items to be errors. In any case, all current docs can be fixed. First, your questions as to what you did not fix. fsum: I personally would add the import visibly, but at least add it hidden, as Chris suggested. 171 >>> from filecmp import dircmp 172 >>> def print_diff_files(dcmp): 173 ... for name in dcmp.diff_files: 174 ... print("diff_file %s found in %s and %s" % (name, dcmp.left, 175 ... dcmp.right)) 176 ... for sub_dcmp in dcmp.subdirs.values(): 177 ... print_diff_files(sub_dcmp) 178 ... 179 >>> dcmp = dircmp('dir1', 'dir2') 180 >>> print_diff_files(dcmp) (copying from the repository view deletes whitespace) The import and def should run and should be tested. The last 2 lines should not be tested: add #doctest: SKIP to both. (I gather that Sphinx will strip this.)
I believe the problem here is the "end = ''" part. It puts a blank space at the end of each line, which got deleted when I pasted the above, which was cut from my local repository. Trailing blanks are *really* a problem and code that produces them is not a good example. I suggest changing width to 6, end to '', and adding '' to the beginning of each output line. It should then pass. ---------- type: enhancement -> behavior versions: +Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Chris Jerdonek added the comment:
Trailing blanks are *really* a problem
The NORMALIZE_WHITESPACE doctest directive is another option to deal with cases like these. It ignores whitespace-only differences between the actual and expected outputs. Does it pass with that directive? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Terry J. Reedy added the comment: Now your patch: colorsys: same change all versions fractions: ditto Template: ditto I believe the changes I suggested for filecmp and the numbers should also be the same in all versions. ACKS: your name should be inserted in alpha order ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Terry J. Reedy added the comment: I considered the directive, but I mildly prefer the code change. end = ' ') guarantees a blank between fields even if one formats a too-large number end = '') does not add a blank to the end. end = '' if base == 'b' else ' ') does both (but depends on having a 'last field' condition. I actual practice, I might use the third option. However, if you do the commit, it is your choice. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Chris Jerdonek added the comment:
I considered the directive, but I mildly prefer the code change.
I just wanted to point the directive out as an available option (especially for Ravi if he does further patches like this). Either way is fine with me. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Terry J. Reedy added the comment: Apparently, I should have suggested "# doctest: +SKIP". The #12947 fix to example directives being deleted from the directive examples came after the 3.3.0 release. Fixed examples are at http://docs.python.org/py3k/library/doctest.html#option-flags-and-directives ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Ravi Sinha added the comment: I've used the testsetup directive and the problem in http://hg.python.org/cpython/file/40a1652349e9/Doc/library/math.rst, line 79, is fixed; the test passes Added # doctest: +SKIP to lines 179 and 180 in http://hg.python.org/cpython/file/40a1652349e9/Doc/library/filecmp.rst, and it passes too For http://hg.python.org/cpython/file/40a1652349e9/Doc/library/string.rst, lines 612-624, used +NORMALIZE_WHITESPACE and the test passed, but since Terry preferred a code change, did that too; the test passes Put my name at the proper position in Misc/ACKS For the multiple versions, I needed to ask whether they'd all belong to this same patch or there would be different patches for each version? Sorry if it's a silly question; I haven't had the time to wrap my head around how to best work with all the versions together With the directives Chris and Terry suggested, it should be easy to make several other tests pass; I'll make a few more patches ---------- Added file: http://bugs.python.org/file27574/doc_lib_Oct14_2012.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Changes by Ravi Sinha <rss1406@gmail.com>: Added file: http://bugs.python.org/file27649/27.doc_lib_Oct21_2012.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Changes by Ravi Sinha <rss1406@gmail.com>: Added file: http://bugs.python.org/file27650/32.doc_lib_Oct21_2012.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Changes by Ravi Sinha <rss1406@gmail.com>: Added file: http://bugs.python.org/file27651/33.doc_lib_Oct21_2012.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Ravi Sinha added the comment: Based on what I saw on some other issues, I think there is just a separate patch for each version (coming from separate working repositories), but all attached to the same issue. So I am doing the same. All the changes have been made to files under Doc/library/ - colorsys.rst, filecmp.rst, fractions.rst, math.rst, string.rst and Misc/ACKS. The beginning number for each patch and the description show which version it's meant for. There are some minor differences for 2.7 and 3.2; they either did not need a fix or needed some more tests to be skipped. For 2.7 and 3.2 I don't know how to use the online source browser to link the files directly. Please let me know if the patches are okay or how to go from here. Thanks. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ezio.melotti stage: -> patch review _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Roundup Robot added the comment: New changeset 9b3d0bdb9256 by Ezio Melotti in branch '2.7': #16154: fix some doctests in Doc/library. Patch by Ravi Sinha. http://hg.python.org/cpython/rev/9b3d0bdb9256 New changeset 5b405df8518d by Ezio Melotti in branch '3.2': #16154: fix some doctests in Doc/library. Patch by Ravi Sinha. http://hg.python.org/cpython/rev/5b405df8518d New changeset 3e884b3804b3 by Ezio Melotti in branch '3.3': #16154: merge with 3.2. http://hg.python.org/cpython/rev/3e884b3804b3 New changeset 5ec8daab477a by Ezio Melotti in branch 'default': #16154: merge with 3.3. http://hg.python.org/cpython/rev/5ec8daab477a ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
Ezio Melotti added the comment: Fixed, thanks for the report and the patch! ---------- assignee: docs@python -> ezio.melotti resolution: -> fixed stage: patch review -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16154> _______________________________________
participants (5)
-
Chris Jerdonek -
Ezio Melotti
-
Ravi Sinha
-
Roundup Robot
-
Terry J. Reedy