[Numpy-discussion] Code samples in docstrings mistaken as doctests
Mon Jun 23 15:07:13 CDT 2008
Mon, 23 Jun 2008 15:53:55 -0400, Anne Archibald wrote:
> 2008/6/23 Alan McIntyre <email@example.com>:
>> On Mon, Jun 23, 2008 at 3:21 PM, Stéfan van der Walt <firstname.lastname@example.org>
>>> Another alternative is to replace +SKIP with something like +IGNORE.
>>> That way, the statement is still executed, we just don't care about
>>> its outcome. If we skip the line entirely, it often affects the rest
>>> of the tests later on.
>> Ugh. That just seems like a lot of unreadable ugliness to me. If this
>> comment magic is the only way to make that stuff execute properly under
>> doctest, I think I'd rather just skip it in favor of clean,
>> uncluttered, non-doctestable code samples in the docstrings. If the
>> code that's currently in docstrings needs to be retained as test code,
>> I'll gladly take the time to put it into a test_ module where it
>> doesn't get in the way of documentation. I'll defer to the consensus,
> I think doctests are valuable: it's very hard for the documentation to
> get out of sync with the code, and it makes it very easy to write tests,
> particularly in light of the wiki documentation framework. But I think
> encrusting examples with weird comments will be a pain for documentors
> and off-putting to users. Perhaps doctests can be positively marked, in
> some relatively unobtrusive way?
I also think being able to test that the examples in docstrings run
correctly could be valuable, but I'm not sure if it makes sense to have
this enabled in the default test set.
Another idea (in addition to whitelisting): how easy would it be to
subclass doctest.DocTestParser so that it would eg. automatically +IGNORE
any doctest lines containing ">>> plt."?
More information about the Numpy-discussion