classification
Title: #doctest: directives removed from doctest chapter examples
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: duplicate
Dependencies: Superseder: doctest directive examples in library/doctest.html lack the flags
View: 12947
Assigned To: docs@python Nosy List: Devin Jeanpierre, docs@python, eric.araujo, ezio.melotti, georg.brandl, sandro.tosi, terry.reedy
Priority: normal Keywords:

Created on 2012-05-20 17:58 by terry.reedy, last changed 2012-05-20 21:43 by terry.reedy. This issue is now closed.

Messages (6)
msg161220 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-05-20 17:58
In the doctest section, 25.2.3.5. Option Flags and Directives has examples of using #doctest: directives in the .rst source
'''
An example's doctest directives modify doctest's behavior for that single example.  Use ``+`` to enable the named behavior, or ``-`` to disable it.

For example, this test passes::

   >>> print(list(range(20))) #doctest: +NORMALIZE_WHITESPACE
   [0,   1,  2,  3,  4,  5,  6,  7,  8,  9,
   10,  11, 12, 13, 14, 15, 16, 17, 18, 19]
'''
However, when converted to html or Window's help, the directive is removed. See for example

http://docs.python.org/py3k/library/doctest.html#option-flags-and-directives

This was reported on python-list for 2.7 and 3.? (.2 probably) by Steven D'Aprano and verified by me for 3.3.0 Win help. Vincent Vande Vyvre provided quote from 3.? .rst source and I verified it and several more following in 3.3.0.

I presume the problem is that we now use the same directives to help doctest source examples for other modules and sphinx with our customizations does not know to leave these particular directives in the text after using them.

I searched issues for '#doctest' and did not see anything about removal.
msg161221 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-05-20 18:14
This is a somewhat recent reversion.

3.1.5 (a month ago)
http://docs.python.org/release/3.1.5/library/doctest.html#module-doctest
>>> print(list(range(20))) #doctest: +NORMALIZE_WHITESPACE
[0,   1,  2,  3,  4,  5,  6,  7,  8,  9,
10,  11, 12, 13, 14, 15, 16, 17, 18, 19]

3.2.0
http://docs.python.org/release/3.2/library/doctest.html#module-doctest
>>> print(list(range(20))) 
[0,   1,  2,  3,  4,  5,  6,  7,  8,  9,
10,  11, 12, 13, 14, 15, 16, 17, 18, 19]

In Py 2, the same change happened between 2.7.2, released June 2011 after 3.2.0, and 2.7.3. So some change was made for 3.2.0 but not ported to 2.7 until several months later, and never ported to 3.1 (or 2.6). I hope this helps.
msg161224 - (view) Author: Sandro Tosi (sandro.tosi) * (Python committer) Date: 2012-05-20 18:45
Hi Terry,
the same problem recently came up on docs@ and digging into it, it turned out that sphinx is currently ignoring doctest directives[1], but that it was fixed in sphinx 1.1[2].

[1] https://bitbucket.org/birkenfeld/sphinx/issue/169/strip-doctest-csomments-in-rendered-output
[2] https://bitbucket.org/birkenfeld/sphinx/changeset/d91bf8e465ef

It's likely the bug is visible on the active branches because recently they were updated to use the same sphinx version.

We can probably plan to update the sphinx we use for the doc - what do you think about it?
msg161226 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-05-20 19:28
To my mind, stripping is not ignoring ;-), but I understand what you mean, sphinx ignores as it pays attention and strips.

[2] is the commit for [1], and both are from 3 years ago, long before 3.2.0. Does the true-by-default ``trim_doctest_flags`` config value work on a file by file basis, so that it can just be added to doctest.rst?

I have no opinion of sphinx versions, which I am ignorant about. I just know that the mistaken stripping destroys the value of the examples, making the result very confusing.
msg161227 - (view) Author: Devin Jeanpierre (Devin Jeanpierre) * Date: 2012-05-20 19:35
This is a duplicate of http://bugs.python.org/issue12947
msg161234 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-05-20 21:42
Thanks for discovering that. I did not search well enough.
History
Date User Action Args
2012-05-20 21:43:40terry.reedysetsuperseder: doctest directive examples in library/doctest.html lack the flags
2012-05-20 21:42:13terry.reedysetstatus: open -> closed
resolution: duplicate
messages: + msg161234

stage: needs patch -> resolved
2012-05-20 19:35:43Devin Jeanpierresetnosy: + Devin Jeanpierre
messages: + msg161227
2012-05-20 19:28:10terry.reedysetmessages: + msg161226
2012-05-20 18:45:19sandro.tosisetnosy: + sandro.tosi
messages: + msg161224
2012-05-20 18:14:01terry.reedysetmessages: + msg161221
2012-05-20 17:58:14terry.reedycreate