classification
Title: Some minor doc fixes in Doc/library
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 3.4, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: Ravi.Sinha, chris.jerdonek, docs@python, ezio.melotti, python-dev, r.david.murray, terry.reedy
Priority: normal Keywords: patch

Created on 2012-10-06 22:25 by Ravi.Sinha, last changed 2013-01-11 07:14 by ezio.melotti. This issue is now closed.

Files
File name Uploaded Description Edit
doc_lib.patch Ravi.Sinha, 2012-10-06 22:25 Minor doc fixes in Doc/library for doctest review
doc_lib_Oct14_2012.patch Ravi.Sinha, 2012-10-14 22:04 Enhancing the patch based on suggestions review
27.doc_lib_Oct21_2012.patch Ravi.Sinha, 2012-10-21 19:08 Patch for 2.7 review
32.doc_lib_Oct21_2012.patch Ravi.Sinha, 2012-10-21 19:09 Patch for 3.2 review
33.doc_lib_Oct21_2012.patch Ravi.Sinha, 2012-10-21 19:09 Patch for 3.3 review
Messages (12)
msg172253 - (view) Author: Ravi Sinha (Ravi.Sinha) Date: 2012-10-06 22:25
- 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.
msg172296 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-10-07 12:45
> 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.
msg172328 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-10-07 18:33
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.)

   >>> width = 5
   >>> for num in range(5,12):
   ...     for base in 'dXob':
   ...         print('{0:{width}{base}}'.format(num, base=base, width=width), end=' ')
   ...     print()
   ...
       5     5     5   101
       6     6     6   110
       7     7     7   111
       8     8    10  1000
       9     9    11  1001
      10     A    12  1010
      11     B    13  1011

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.
msg172329 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-10-07 18:44
> 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?
msg172330 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-10-07 18:48
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
msg172331 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-10-07 19:04
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.
msg172333 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-10-07 19:10
> 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.
msg172337 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-10-07 19:43
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
msg172928 - (view) Author: Ravi Sinha (Ravi.Sinha) Date: 2012-10-14 22:04
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
msg173470 - (view) Author: Ravi Sinha (Ravi.Sinha) Date: 2012-10-21 19:12
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.
msg179640 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-01-11 07:13
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
msg179641 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-01-11 07:14
Fixed, thanks for the report and the patch!
History
Date User Action Args
2013-01-11 07:14:38ezio.melottisetstatus: open -> closed
messages: + msg179641

assignee: docs@python -> ezio.melotti
resolution: fixed
stage: patch review -> resolved
2013-01-11 07:13:10python-devsetnosy: + python-dev
messages: + msg179640
2013-01-07 06:24:34ezio.melottisetnosy: + ezio.melotti

stage: patch review
2012-10-21 19:12:39Ravi.Sinhasetmessages: + msg173470
2012-10-21 19:09:16Ravi.Sinhasetfiles: + 33.doc_lib_Oct21_2012.patch
2012-10-21 19:09:02Ravi.Sinhasetfiles: + 32.doc_lib_Oct21_2012.patch
2012-10-21 19:08:36Ravi.Sinhasetfiles: + 27.doc_lib_Oct21_2012.patch
2012-10-14 22:04:22Ravi.Sinhasetfiles: + doc_lib_Oct14_2012.patch

messages: + msg172928
2012-10-07 19:43:41terry.reedysetmessages: + msg172337
2012-10-07 19:10:36chris.jerdoneksetmessages: + msg172333
2012-10-07 19:04:58terry.reedysetmessages: + msg172331
2012-10-07 18:48:50terry.reedysetmessages: + msg172330
2012-10-07 18:44:50chris.jerdoneksetmessages: + msg172329
2012-10-07 18:33:43terry.reedysettype: enhancement -> behavior
messages: + msg172328
versions: + Python 2.7, Python 3.2, Python 3.3
2012-10-07 12:45:17chris.jerdoneksetmessages: + msg172296
2012-10-06 22:25:25Ravi.Sinhacreate