[Biopython-dev] docstring tests

[Peter]

> On Wed, Feb 11, 2009 at 2:06 AM, Michiel de Hoon wrote:
>> Hi everybody,
>>
>> I included the code to run the docstring tests to run_tests.py, which means that now they're run after the test_*.py tests have finished:

That's nice, and arguably better than the test_docstring.py solution.
In the medium/long term we may want to switch to an automatic
detection of these tests.

Do you think we need a way to run just the doctests?  Before we could
do "python run_tests.py test_docstring.py" to do this.

On Wed, Feb 11, 2009 at 9:16 AM, Giovanni Marco Dall'Olio
<dalloliogm at gmail.com> wrote:
> As for the doctests, it would be really be useful to define some
> global fixtures.
> It will reduce the docstrings lengths and we won't have to repeat all
> the examples in every method of every function, we won't have to
> repeat the 'from Bio import ..' in every test and so on.
> How this could be implemented in this test framework?

I disagree here.  If you have any import statements (or any other
global fixtures) missing from the individual docstring examples this
reduces their value as documentation (you have to explain somewhere
what is missing, and make sure the user knows this).  Including any
required import statements is only a small overhead for the person
writing the doctest examples and it makes the examples self contained
(which I think is important for documentation).

I can understand for example in NumPy that they might have a global
"import numpy as np" done implicitly in all their tests, but they have
a very flat namespace where this same line would otherwise be repeated
for every single doctest.  This is one "magic line of code" which
would be the same for all the examples, and omitting it is more
justified.

Peter