Python doctests / sphinx : style guide, how to use those and have a readable code ?

Question

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 ? Is there a style guide for doctests, for sphinx ? For docstring with sphinx, do you use google or sphinx style-guide or something else ?

Answer 1

I think there are two sorts of doctest.

1. You can put something in the docstring for the function, but if so keep it short and simple.
2. The other option is full documentation/tutorial, and I do that as a separate file.

Unlike ordinary documentation, the beauty of doctesting is that you can be sure they are going to stay in sync with the code even if they aren't in the same screen. When reading the code you want to see code, perhaps with a little descriptive text. When reading a tutorial you don't want to see the code just the examples.