classification
Title: doctest directive examples in library/doctest.html lack the flags
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.3, Python 3.2, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: chris.jerdonek, docs@python, eric.araujo, ezio.melotti, georg.brandl, ncoghlan, python-dev, sandro.tosi, taschini, terry.reedy
Priority: normal Keywords: patch

Created on 2011-09-09 17:22 by eric.araujo, last changed 2012-10-11 04:27 by terry.reedy. This issue is now closed.

Files
File name Uploaded Description Edit
issue12947_v0.patch taschini, 2012-04-30 14:15 review
Messages (33)
msg143775 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-09-09 17:22
The docs for the doctest module contains examples that use doctest flags to control behavior, but the HTML version does not contain the flags, making the examples useless.

I don’t know if this is a bug with the HTML builder or something we can fix in markup.
msg143777 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-09-09 17:30
Ezio prompted me to give precise examples, and I can’t find any in the docs online.  Maybe it was only a local build with certain options that caused this problem, I’ll reopen if I find out.
msg143780 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2011-09-09 17:36
Hehe... Sphinx makes a point of *removing* doctest flags, to enable doctesting of code snippets without distracting the reader with the test-internal flags.

I think it's because you used a newer version locally.
msg158600 - (view) Author: Stefano Taschini (taschini) * Date: 2012-04-18 08:55
Concrete examples can be seen in the section

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

For instance at

http://docs.python.org/library/doctest.html#doctest.IGNORE_EXCEPTION_DETAIL

The doctest flags present in the sources in 

http://docs.python.org/_sources/library/doctest.txt

are all stripped.
msg158621 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-04-18 13:52
Thank you.  I think it’s clear that for the docs of the doctest flags we need to display snippets with the flags.
msg158732 - (view) Author: Stefano Taschini (taschini) * Date: 2012-04-19 14:32
As far as I can see, Sphinx has a global setting for trim_doctest_flags but lacks the possibility of locally disabling the trimming.

A quick workaround would be to have the following sphinx extension added:

class ProxyLexer(object):

    def __init__(self, underlying):
        self.__underlying = underlying

    def __getattr__(self, attr):
        return getattr(self.__underlying, attr)

def setup(app):
    from sphinx.highlighting import lexers
    if lexers is not None:
        lexers['pycon-literal'] = ProxyLexer(lexers['pycon'])
        lexers['pycon3-literal'] = ProxyLexer(lexers['pycon3'])

That would allow blocks marked as

.. code-block:: pycon-literal

or preceded by 

.. highlight:: pycon-literal

to escape the trimming of doctest flags.

If that's of any interest I can submit a patch.
msg159593 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-04-29 09:25
Is there a way to add a :keep-doctest-flags: options to literal blocks?
msg159697 - (view) Author: Stefano Taschini (taschini) * Date: 2012-04-30 14:15
Ezio, the patch I attached goes into that direction, by adding a ":trim-doctest-flags: disable" option to the code blocks.

I thought I had a good reason for having the option worded as ":trim-doctest-flags: disable" instead of ":keep-doctest-flags:", now I'm not so sure.

Note: the patch is against the 2.7 branch.
msg161232 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-05-20 21:10
The directives should normally be stripped, but not when they are intentionally given to teach their existence, syntax, and use, as in the doctest doc on directives.

I opened (and closed -- am trying to anyway) a duplicate, #14865. The problem of directive stripping started in 3.2.0 and subsequently 2.7.3 (after 2.7.2 in June 2011) and contiues in 3.3.0. Sandro Tosi noted

[1] https://bitbucket.org/birkenfeld/sphinx/issue/169/strip-doctest-csomments-in-rendered-output
[2] https://bitbucket.org/birkenfeld/sphinx/changeset/d91bf8e465ef
Issue and commit from June 2009.

My question is whether the added true-by-default ``trim_doctest_flags`` config value can just be added to doctest.rst? That would seem to be the point of having a settable config value, but I am ignorant of how sphinx works. I see that the patch does that, but also a lot more.

In any case, this is a nasty regression in the docs and should be fixed somehow before the next releases. It makes the examples actively confusing.
msg170160 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-09-10 06:47
I discovered this today as well while reading the doctest documentation.

One thing that I never noticed before (and that doesn't seem to be reflected in the comments above) is that many of the code snippet rectangles in the doctest documentation have a small rectangle in the upper-right corner with the text ">>>".

If you click on one of these small rectangles, most of the text inside the code snippet rectangle disappears.  I haven't confirmed this, but I suspect that it is the code snippets with a doctest directive that have this clickable corner.

Is this a feature?  What is it for? :)
msg170184 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-09-10 12:30
> Is this a feature?  What is it for? :)

The >>> is added to every example that contains an interactive session to hide the '>>>' and '...' prompts and the output and make the code copy/pastable, and it's not specific to doctests.
msg171858 - (view) Author: Roundup Robot (python-dev) Date: 2012-10-03 06:48
New changeset 662fb4bd5f84 by Nick Coghlan in branch '2.7':
Issue #12947: Add a note to doctest until the example rendering is fixed
http://hg.python.org/cpython/rev/662fb4bd5f84
msg171859 - (view) Author: Roundup Robot (python-dev) Date: 2012-10-03 06:52
New changeset 679b3e3aadae by Nick Coghlan in branch '3.3':
Issue #12947: Add a note to doctest until the example rendering is fixed
http://hg.python.org/cpython/rev/679b3e3aadae
msg171860 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2012-10-03 06:54
Since the status quo is thoroughly confusing for readers, I added an explicit note before the affected examples. That note should be removed once the rendering problem is fixed. (The note is there on trunk as well, I just forgot to include the issue number in the merge commit)
msg171862 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-10-03 07:12
I thought of an easy work-around we can use after looking at the changeset Terry referenced above:

> [2] https://bitbucket.org/birkenfeld/sphinx/changeset/d91bf8e465ef

At the expense of pretty color highlighting, we can enable Pygments' TextLexer for the affected examples (aka "null" lexer).  For example--

.. code-block:: text

   >>> raise CustomError('message') #doctest: +IGNORE_EXCEPTION_DETAIL
   Traceback (most recent call last):
   CustomError: message

I confirmed locally that this works.  I realized this might work because the Sphinx changeset referenced above has this logic:

    # trim doctest options if wanted
    if isinstance(lexer, PythonConsoleLexer) and self.trim_doctest_flags:
msg171866 - (view) Author: Roundup Robot (python-dev) Date: 2012-10-03 08:18
New changeset 18d927fb8671 by Nick Coghlan in branch '2.7':
Issue #12947: Better workaround for the problem with doctest directives being stripped from code examples that are intended to illustrate those directives
http://hg.python.org/cpython/rev/18d927fb8671
msg171868 - (view) Author: Roundup Robot (python-dev) Date: 2012-10-03 08:23
New changeset d93a59a0a984 by Nick Coghlan in branch '3.3':
Issue #12947: Better workaround for the problem with doctest directives being stripped from code examples that are intended to illustrate those directives
http://hg.python.org/cpython/rev/d93a59a0a984

New changeset 26200f535296 by Nick Coghlan in branch 'default':
Merge #12947 workaround from 3.3
http://hg.python.org/cpython/rev/26200f535296
msg171869 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2012-10-03 08:25
Adopted Chris's workaround for now. I kept a reworded version of the preceding note (with the link to this bug), so readers know that the lack of syntax highlighting is intended-but-not-desired.
msg171871 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-10-03 08:35
Thanks, Nick.  It looks like there are a few more though?  I'm counting four more in default (search for "doctest:"): three IGNORE_EXCEPTION_DETAIL and one ELLIPSIS.
msg171874 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2012-10-03 09:00
I only changed the ones that were specifically in the section explaining doctest directives. There are probably others, but it didn't seem necessary to change them and lose the syntax highlighting at this point.
msg172336 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-10-07 19:42
http://docs.python.org/py3k/library/doctest.html#option-flags-and-directives

has the improved version. Thanks. Here, the complete example text is more important than the hi-lites.
msg172368 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2012-10-08 09:20
Ah, I see the other examples Chris is talking about now. Yes, the workaround should be applied in those cases as well.
msg172575 - (view) Author: Roundup Robot (python-dev) Date: 2012-10-10 14:21
New changeset 00555659253d by Chris Jerdonek in branch '3.3':
Issue #12947: Divide doctest "Option Flags and Directives" section into two.
http://hg.python.org/cpython/rev/00555659253d

New changeset 467c9f663b77 by Chris Jerdonek in branch 'default':
Issue #12947: Merge doctest documentation improvements from 3.3.
http://hg.python.org/cpython/rev/467c9f663b77

New changeset 15bfa778ec21 by Chris Jerdonek in branch '2.7':
Issue #12947: Backport doctest documentation improvements from 3.3.
http://hg.python.org/cpython/rev/15bfa778ec21
msg172576 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-10-10 14:28
> Yes, the workaround should be applied in those cases as well.

I added the workaround to the last remaining example.  Nick was right before in that three of the four examples I mentioned above were in the part about "option flags" rather than in the part about "directives".  I made those two parts into their own sections for added clarity.
msg172578 - (view) Author: Roundup Robot (python-dev) Date: 2012-10-10 14:50
New changeset 9057da41cf0b by Georg Brandl in branch '3.2':
Issue #12947: revert earlier workaround and use a monkey-patch to enable showing doctest directives only in the doctest docs.
http://hg.python.org/cpython/rev/9057da41cf0b

New changeset 1202c1449d83 by Georg Brandl in branch '3.3':
Issue #12947: revert earlier workaround and use a monkey-patch to enable showing doctest directives only in the doctest docs.
http://hg.python.org/cpython/rev/1202c1449d83
msg172580 - (view) Author: Roundup Robot (python-dev) Date: 2012-10-10 14:53
New changeset ffe9f644d5af by Georg Brandl in branch '2.7':
Issue #12947: revert earlier workaround and use a monkey-patch to enable showing doctest directives only in the doctest docs.
http://hg.python.org/cpython/rev/ffe9f644d5af
msg172581 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-10-10 15:01
Thanks, Georg.  Can this new directive be applied to individual code blocks though (or be modified to do so)?

After a closer review (as mentioned in my comment above), it seems that the doctest directives should only be displayed in the code snippets that are illustrating the use of doctest directives (as opposed to, say, the snippets that are illustrating doctest options without using directives).
msg172582 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2012-10-10 15:03
I don't see any blocks in doctest.rst where the directives should be stripped, so it's enough to do it per-file.
msg172585 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-10-10 15:07
Like these that discuss the behavior of the doctest.IGNORE_EXCEPTION_DETAIL option (but before doctest directives have been introduced):

http://hg.python.org/cpython/file/0d6910bef979/Doc/library/doctest.rst#l543

The key is that you can have options take effect without using directives, so it would be good if people can see examples like that.
msg172586 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-10-10 15:20
Georg suggested removing the doctest directives from the examples I mentioned.  As currently written, they don't help them pass if doctest were run on the .rst file.  That sounds fine to me for now.
msg172587 - (view) Author: Roundup Robot (python-dev) Date: 2012-10-10 15:40
New changeset 705a70b0fff4 by Chris Jerdonek in branch '3.3':
Issue #12947: Remove doctest directives from the doctest examples in the "Option Flag" section.
http://hg.python.org/cpython/rev/705a70b0fff4

New changeset 9475fc82768e by Chris Jerdonek in branch 'default':
Issue #12947: Merge doctest documentation change from 3.3.
http://hg.python.org/cpython/rev/9475fc82768e

New changeset 8704f9e7ad7c by Chris Jerdonek in branch '2.7':
Issue #12947: Backport doctest documentation change from 3.3.
http://hg.python.org/cpython/rev/8704f9e7ad7c
msg172615 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-10-11 02:15
This seems to look good now.  Can this be closed, or is there something else that needed to be done as well?
msg172618 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-10-11 04:27
I looked at
http://docs.python.org/py3k/library/doctest.html#directives
and the examples with directives looked fine to me, with directive, syntax markup, and 'hide prompt' box. I also checked the next section and saw the one example that needed to have the directive visible. Really nice.
History
Date User Action Args
2012-10-11 04:27:19terry.reedysetstatus: pending -> closed

messages: + msg172618
stage: commit review -> resolved
2012-10-11 02:15:17chris.jerdoneksetstatus: open -> pending
resolution: fixed
messages: + msg172615

stage: needs patch -> commit review
2012-10-10 15:40:16python-devsetmessages: + msg172587
2012-10-10 15:20:24chris.jerdoneksetmessages: + msg172586
2012-10-10 15:07:48chris.jerdoneksetmessages: + msg172585
2012-10-10 15:03:09georg.brandlsetmessages: + msg172582
2012-10-10 15:01:44chris.jerdoneksetmessages: + msg172581
2012-10-10 14:53:05python-devsetmessages: + msg172580
2012-10-10 14:50:44python-devsetmessages: + msg172578
2012-10-10 14:28:40chris.jerdoneksetmessages: + msg172576
2012-10-10 14:21:23python-devsetmessages: + msg172575
2012-10-08 09:20:22ncoghlansetmessages: + msg172368
2012-10-07 19:42:59terry.reedysetmessages: + msg172336
2012-10-03 09:00:04ncoghlansetmessages: + msg171874
2012-10-03 08:35:45chris.jerdoneksetmessages: + msg171871
2012-10-03 08:25:13ncoghlansetmessages: + msg171869
2012-10-03 08:23:39python-devsetmessages: + msg171868
2012-10-03 08:18:27python-devsetmessages: + msg171866
2012-10-03 07:12:21chris.jerdoneksetmessages: + msg171862
2012-10-03 06:54:30ncoghlansetnosy: + ncoghlan
messages: + msg171860
2012-10-03 06:52:30python-devsetmessages: + msg171859
2012-10-03 06:48:36python-devsetnosy: + python-dev
messages: + msg171858
2012-09-10 12:30:51ezio.melottisetmessages: + msg170184
2012-09-10 06:47:26chris.jerdoneksetnosy: + chris.jerdonek
messages: + msg170160
2012-05-22 14:18:23ezio.melottilinkissue14883 superseder
2012-05-20 21:43:40terry.reedylinkissue14865 superseder
2012-05-20 21:10:46terry.reedysetnosy: + terry.reedy
messages: + msg161232
2012-05-20 19:51:04sandro.tosisetnosy: + sandro.tosi
2012-05-20 19:39:16Devin Jeanpierresettitle: Examples in library/doctest.html lack the flags -> doctest directive examples in library/doctest.html lack the flags
2012-04-30 14:15:03taschinisetfiles: + issue12947_v0.patch
keywords: + patch
messages: + msg159697
2012-04-29 09:25:22ezio.melottisettype: enhancement
messages: + msg159593
stage: test needed -> needs patch
2012-04-19 14:32:43taschinisetmessages: + msg158732
2012-04-18 13:52:23eric.araujosetstatus: closed -> open
resolution: not a bug -> (no value)
messages: + msg158621

stage: resolved -> test needed
2012-04-18 08:55:00taschinisetnosy: + taschini
messages: + msg158600
2011-09-09 17:36:32georg.brandlsetmessages: + msg143780
2011-09-09 17:30:07eric.araujosetstatus: open -> closed
resolution: not a bug
messages: + msg143777

stage: resolved
2011-09-09 17:25:41ezio.melottisetnosy: + ezio.melotti
2011-09-09 17:22:33eric.araujocreate