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 document that contains the entire body of the source code along with explanatory notes and design details. Literate programming isn't simple, but it can produce good code coupled with a resulting document that is very clear and complete.
