Repository navigation
doctest directive examples in library/doctest.html lack the flags #57156
Description
| BPO | 12947 |
|---|---|
| Nosy | @birkenfeld, @terryjreedy, @ncoghlan, @ezio-melotti, @merwok, @sandrotosi, @cjerdonek, @taschini |
| Files |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = None
closed_at = <Date 2012-10-11.04:27:19.053>
created_at = <Date 2011-09-09.17:22:33.554>
labels = ['type-feature', 'docs']
title = 'doctest directive examples in library/doctest.html lack the flags'
updated_at = <Date 2012-10-11.04:27:19.053>
user = 'https://github.com/merwok'bugs.python.org fields:
activity = <Date 2012-10-11.04:27:19.053>
actor = 'terry.reedy'
assignee = 'docs@python'
closed = True
closed_date = <Date 2012-10-11.04:27:19.053>
closer = 'terry.reedy'
components = ['Documentation']
creation = <Date 2011-09-09.17:22:33.554>
creator = 'eric.araujo'
dependencies = []
files = ['25424']
hgrepos = []
issue_num = 12947
keywords = ['patch']
message_count = 33.0
messages = ['143775', '143777', '143780', '158600', '158621', '158732', '159593', '159697', '161232', '170160', '170184', '171858', '171859', '171860', '171862', '171866', '171868', '171869', '171871', '171874', '172336', '172368', '172575', '172576', '172578', '172580', '172581', '172582', '172585', '172586', '172587', '172615', '172618']
nosy_count = 10.0
nosy_names = ['georg.brandl', 'terry.reedy', 'ncoghlan', 'ezio.melotti', 'eric.araujo', 'sandro.tosi', 'chris.jerdonek', 'docs@python', 'python-dev', 'taschini']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue12947'
versions = ['Python 2.7', 'Python 3.2', 'Python 3.3']
Activity
merwok commentedon Sep 9, 2011
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.
merwok commentedon Sep 9, 2011
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.
birkenfeld commentedon Sep 9, 2011
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.
taschini commentedon Apr 18, 2012
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.
merwok commentedon Apr 18, 2012
Thank you. I think it’s clear that for the docs of the doctest flags we need to display snippets with the flags.
taschini commentedon Apr 19, 2012
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:
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.
ezio-melotti commentedon Apr 29, 2012
Is there a way to add a :keep-doctest-flags: options to literal blocks?
taschini commentedon Apr 30, 2012
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.
13 remaining items
terryjreedy commentedon Oct 7, 2012
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.
ncoghlan commentedon Oct 8, 2012
Ah, I see the other examples Chris is talking about now. Yes, the workaround should be applied in those cases as well.
python-dev commentedon Oct 10, 2012
New changeset 00555659253d by Chris Jerdonek in branch '3.3':
Issue bpo-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 bpo-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 bpo-12947: Backport doctest documentation improvements from 3.3.
http://hg.python.org/cpython/rev/15bfa778ec21
cjerdonek commentedon Oct 10, 2012
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.
python-dev commentedon Oct 10, 2012
New changeset 9057da41cf0b by Georg Brandl in branch '3.2':
Issue bpo-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 bpo-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
python-dev commentedon Oct 10, 2012
New changeset ffe9f644d5af by Georg Brandl in branch '2.7':
Issue bpo-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
cjerdonek commentedon Oct 10, 2012
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).
birkenfeld commentedon Oct 10, 2012
I don't see any blocks in doctest.rst where the directives should be stripped, so it's enough to do it per-file.
cjerdonek commentedon Oct 10, 2012
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.
cjerdonek commentedon Oct 10, 2012
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.
python-dev commentedon Oct 10, 2012
New changeset 705a70b0fff4 by Chris Jerdonek in branch '3.3':
Issue bpo-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 bpo-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 bpo-12947: Backport doctest documentation change from 3.3.
http://hg.python.org/cpython/rev/8704f9e7ad7c
cjerdonek commentedon Oct 11, 2012
This seems to look good now. Can this be closed, or is there something else that needed to be done as well?
terryjreedy commentedon Oct 11, 2012
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.