Hi !

I love doctests, it is the only testing framwork I use, because it is so quick to write, and because used with sphinx it makes such great documentations with almost no effort...

However, very often, I end-up doing things like this :

"""
Descriptions
=============

bla bla bla ...

    >>> test
    1
bla bla bla + tests tests tests * 200 lines = poor readability of the actual code
"""

What I mean is that I put all my tests with documentation explanations on the top of the module, so you have to scroll stupidly to find the actual code, and this is quite ugly (in my opinion). However, I think that the doctests should still stay in the module, because you should be able to read them while reading the source code. So here comes my question : sphinx/doctests lovers, how do you organize your doctests, such as the code readability doesn't suffer ?