Summary

We looked at the following four ways to create usable documentation:

• We can incorporate the information into the docstrings in our software

• We can use pydoc to extract the API reference information from our software.

• We can use Sphinx to create more sophisticated and elaborate documentation

• Also, we can use a literate programming tool to create even deeper and more meaningful documentation

Design considerations and trade-offs

The docstring should be considered as essential as any other part of the Python source. This ensures that the help() function and pydoc will work correctly. As with unit test cases, this should be viewed as a mandatory element of the software.

The documentation created by Sphinx can be very good looking; it will tend to parallel the Python documentation. Our objective all along has been seamless integration with the other features of Python. Using Sphinx tends to introduce an additional directory structure for the documentation source and build.

As we design our classes...