This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author r.david.murray
Recipients JDLH, docs@python, marco.buttu, r.david.murray
Date 2017-02-03.14:42:56
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1486132976.88.0.95919708864.issue29428@psf.upfronthosting.co.za>
In-reply-to
Content
It does appear that "test" is being used ambiguously in the docs.  In most places it means a single statement, but in execution context it appears to be being used as a synonym for "docstring".  In that section it should be replaced by "docstring".  It would probably be worth checking the rest of the doc to make sure it is used consistently elsewhere as well.

As for the prompts, I agree with Marco: I don't think there is any need to add words, since it clearly says it is supposed to look like an interactive session and the reader gets reminded of the rules for that by the example provided.  IMO it is not appropriate to re-document those rules here.  However, if you come up with a really concise addition that clarifies it, we'll consider it.

I don't think an additional example of using previous state is required, and certainly not an additional section.  The execution context section makes it clear that you can use names defined earlier, as does the fact that doctests emulate interactive sessions.  Both of these make it clear you can do multi line examples that use shared state.  However, if you come up with an example that adds value to the documentation, we'll certainly consider it.

So in summary, I think we *need* a one word change in the execution context section, and we'll consider any other enhancements you want to propose.
History
Date User Action Args
2017-02-03 14:42:56r.david.murraysetrecipients: + r.david.murray, docs@python, marco.buttu, JDLH
2017-02-03 14:42:56r.david.murraysetmessageid: <1486132976.88.0.95919708864.issue29428@psf.upfronthosting.co.za>
2017-02-03 14:42:56r.david.murraylinkissue29428 messages
2017-02-03 14:42:56r.david.murraycreate