[Biopython-dev] docstring tests

[Giovanni Marco Dall'Olio]

On Wed, Feb 11, 2009 at 11:48 AM, Peter <biopython at maubp.freeserve.co.uk> wrote:
>> 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).

On the long run, it will be hard without fixtures: imagine, for
example, the docs in BioSQL, where you will have to put the
instructions to create a new database in every method's docstring of
every class.
I think it is not too bad to face the problem now, before it is too
late, and at least give a general infrastructure for how doctest's
fixtures will have to be in the future.



> 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
>



-- 

My blog on bioinformatics (now in English): http://bioinfoblog.it