Mastering Object-oriented Python

Chapter 18. Quality and Documentation

Good software doesn't just happen; it's crafted. A deliverable product includes readable, accurate documentation. We'll look at two tools to produce the documentation from the code: pydoc and Sphinx. The Sphinx tool is enhanced if we write the documentation using a lightweight markup language. We'll describe some features of ReStructured Text (RST) to help make our documentation more readable.

Documentation is an important quality aspect of software; it is one aspect of building trust. Test cases are another way to build trust. Using doctest to write test cases addresses both the quality aspects.

We'll also take a brief look at literate programming techniques. The idea is to write a pleasant, easy-to-understand ...