| msg161220 - (view) |
Author: Terry J. Reedy (terry.reedy) *  |
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) * |
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) * |
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) * |
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) * |
Date: 2012-05-20 21:42 |
| Thanks for discovering that. I did not search well enough. |
|
|