[issue29428] Doctest documentation unclear about multi-line fixtures

Carol Willing added the comment: I've closed the associated PR https://github.com/python/cpython/pull/45 with a recommendation to resubmit a smaller, more atomic PR if desired. -- nosy: +willingc resolution: -> rejected stage: -> resolved status: open -> closed

[issue29428] Doctest documentation unclear about multi-line fixtures

Jim DeLaHunt added the comment: Bump. Could I get a few more eyes looking at the current state of https://github.com/python/cpython/pull/45/ ? * @bitdancer made some suggestions. I accepted some, and replied to others where I think we should keep looking for common ground. I'd like to see

[issue29428] Doctest documentation unclear about multi-line fixtures

Jim DeLaHunt added the comment: Pull Request https://github.com/python/cpython/pull/45 submitted to new Github repo. I would appreciate a review. I attempted to balance all the different opinions in the discussion below: stay concise, but also improve the clarity. -- pull_requests:

[issue29428] Doctest documentation unclear about multi-line fixtures

Jim DeLaHunt added the comment: I've drafted some fairly restricted changes to the doctest documentation page. They are in my Github branch, https://github.com/JDLH/cpython/tree/Issue29428_doctest_docs . The diffs are at

[issue29428] Doctest documentation unclear about multi-line fixtures

Jim DeLaHunt added the comment: Marco: > To have a wide view, usually it is a good idea to start from the beginning: > > https://groups.google.com/forum/#!msg/comp.lang.python/DfzH5Nrt05E/Yyd3s7fPVxwJ Thank you, that is a very interesting thread. Clearly the creator of doctests, Tim Peters,

[issue29428] Doctest documentation unclear about multi-line fixtures

Marco Buttu added the comment: > In parallel, I was thinking of some howto content that I would like to > see documented. Great :-) > How to decide what to test with doctests and what with unittests. > I have a feeling that the sweet spot of doctests is functionality > which you can invoke in

[issue29428] Doctest documentation unclear about multi-line fixtures

Jim DeLaHunt added the comment: Marco, thank you for the suggestion of a howto. That is a good idea. In parallel, I was thinking of some howto content that I would like to see documented. • How to decide what to test with doctests and what with unittests. I have a feeling that the sweet

[issue29428] Doctest documentation unclear about multi-line fixtures

Marco Buttu added the comment: IMO if you would like to apply big changes to the current doc, as you wrote before, maybe is worth considering to propose a separate howto, instead of wide changes to the current page. I am suggesting this to you, because looking at the other modules of the

[issue29428] Doctest documentation unclear about multi-line fixtures

Jim DeLaHunt added the comment: Marco and David, thank you again for your prompt replies. Let me respond to both of your comments on the doctest module documentation itself. [Marco] > The example in section 26.3.3.2 [1], before the compound statement (the if/else), contains two simple

[issue29428] Doctest documentation unclear about multi-line fixtures

Jim DeLaHunt added the comment: Marco, thank you for the suggestion to watch Raymond Hettinger's talk. > I suggest you to watch this talk of Raymond Hettinger, before going on: > > https://www.youtube.com/watch?v=voXVTjwnn-U That video is 63 minutes long, and a lot of those minutes are taken

[issue29428] Doctest documentation unclear about multi-line fixtures

Jim DeLaHunt added the comment: Marco, thank you for your prompt comment. However, > Maybe you are running the doctest with Python 3. The StringIO module is no > more available in Python 3, so your doctest will fail on Python 3 Please let me be clear. This issue is not about the

[issue29428] Doctest documentation unclear about multi-line fixtures

R. David Murray added the comment: And thanks for wanting to improve the docs! -- ___ Python tracker ___ ___

[issue29428] Doctest documentation unclear about multi-line fixtures

R. David Murray added the comment: It does appear that "test" is being used ambiguously in the docs. In most places it means a single statement, but in execution context it appears to be being used as a synonym for "docstring". In that section it should be replaced by "docstring". It would

[issue29428] Doctest documentation unclear about multi-line fixtures

Marco Buttu added the comment: > I just had a problem with doctests. It manifested as an > error that occurred when I did > >>> import StringIO in my doctest. Maybe you are running the doctest with Python 3. The StringIO module is no more available in Python 3, so your doctest will fail on

[issue29428] Doctest documentation unclear about multi-line fixtures

New submission from Jim DeLaHunt: I just had a problem with doctests. It manifested as an error that occurred when I did >>> import StringIO in my doctest. After some investigation, I realised that my actual problem was that the doctest library documentation