Expert Python Programming - Third Edition

Writing a story

Writing doctests in DDD is done by building a story about how a piece of code works and should be used. These principles are described in plain English and then a few code usage examples are distributed throughout the text. A good practice is to start to write text on how the code works, and then add some code examples.

To see an example of doctests in practice, let's look at the atomisator package (refer to https://bitbucket.org/tarek/atomisator). The documentation text for its atomisator.parser subpackage (under packages/atomisator.parser/atomisator/parser/docs/README.txt) is as follows:

================= atomisator.parser ================= The parser knows how to return a feed content, with the `parse` function, available ...