To be valuable, software must be trusted. The general goal of trustworthiness relies on a number of software quality attributes. For more information on this, refer to the S-Cube Quality Reference Model section in https://s-cube-network.eu/km/qrm/index.html. Good documentation is an underlying technique for demonstrating that the various quality attributes have been met.

In this chapter, we'll look at two tools to produce the documentation from the code: pydoc and Sphinx. The pydoc tool extracts documentation from the Python code and produces useful views of the docstrings. The Sphinx tool allows us to create complete and sophisticated documentation using a lightweight markup language coupled with the source code. We'll describe some features of reStructuredText (RST) to help make our documentation more readable.

For more information, refer to PEP 257 in https://www.python.org/dev/peps/pep-0257/. This describes the minimum standard for docstrings. The use of formatting markup such as RST extends this baseline proposal.

Complete test cases are another aspect of high-quality software. We can use the doctest module to execute test cases. Doing this addresses two quality aspects—documentation and testing—with a single tool.

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.

In this chapter, we will cover the following topics:

• Writing docstrings for the help() function
• Using pydoc for documentation
• Better output via RST markup
• Writing effective docstrings
• Writing file-level docstrings, including modules and packages
• More sophisticated markup techniques
• Using Sphinx to produce the documentation
• Writing the documentation
• Literate programming