[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 rep

[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 https://github.com/JDLH/cpython/commit/223ef8f8a6d2fbec6db774912028abb4d2

[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, i

[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 o

[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 spo

[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 stand

[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 state

[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 u

[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 StringI

[issue29428] Doctest documentation unclear about multi-line fixtures

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

[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 Pyth

[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 https://docs.python.org/3/library/