Differentiate ELLIPSIS from LINE_CONTINUATION in doctest. #1276
Description
I think that differentiating ELLIPSIS from LINE_CONTINUATION in doctests could
improve the usability of doctest blocks in Sphinx.
Using the same symbol is a source of confusion since one can not ignore text
that is present at the beginning of the line, using an ellipsis.
Below a few cases when this might be necessary (I asked about in comp.lang.python,
seeking help for some documentation I am writing ).
The following doctest would fail:
#!python
.. doctest:: example_fake
>>> def myfun(x,verbose):
... print "random output" # this is produced by a 3rd part function, no control over it
... return x
>>> myfun(10)
10
When you run make doctest the test fails with this message:
::
File "tutorial.rst", line 11, in example_fake
Failed example:
myfun(10)
Expected:
10
Got:
random output
10
In this case (imagine that "random output" is really random, therefore I can not easily filter it, if not ignoring several lines. This would be quite easy if ellipsis and line continuation wouldn't have the same sequence of characters, but unfortunately this is not the case.
Similarly the following doctest fails:
#!python
.. doctest::
>>> def myfun(x,verbose):
... print "random output"
... return x
>>> result = myfun(10) #should ignore the output here!
>>> print result
10
fails with this message:
#!python
File "tutorial.rst", line 11, in example_fake
Failed example:
result = myfun(10)
Expected nothing
Got:
random output
(line 11 contains: >>> result = myfun(10))
A SKIP directive here is not feasible:
#!python
.. doctest:: example_fake
>>> def myfun(x):
... print "random output"
... return x
>>> result = myfun(10) # doctest: +SKIP
>>> result
10
fails with this error message:
#!python
File "tutorial.rst", line 12, in example_fake
Failed example:
result
Exception raised:
Traceback (most recent call last):
File "/usr/lib/python2.7/doctest.py", line 1289, in __run
compileflags, 1) in test.globs
File "<doctest example_fake[2]>", line 1, in <module>
result
NameError: name 'result' is not defined
I know that it is a rare circumstance and that it is fault of how doctest mode has implemented the ELLIPSIS and the LINE_CONTINUATION using the same sequence
of symbols, rather than Sphinx's fault.
I believe though that it might be helpful to be able to distinguish the two, and creating test code that works as intended.
Thanks for considering it,
Cheers,
Luca
- Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/1276
- Originally reported by: Luca Cerone
- Originally created at: 2013-09-27T19:15:17.756