Documenting the code

There are, broadly, three levels of documentation. At the top, you have project- or distribution-level documentation. It is intended to give high-level information on a project, such as installation instructions, licensing terms, and so on. In Chapter 3, Modularize, Package, Deploy!, you already had a flavor of this documentation. We created the README and LICENSE files to go along with the distribution. Additionally, you can add more files to make the documentation comprehensive, such as INSTALL, TODO, RELEASENOTES, CREDITS, and so on.

The second level is the API-level documentation. It summarizes how a function, method, class, or module should be used. Python docstrings, which we will learn next, are used to generate API-level documentation.

The third level of documentation is in the form of code comments. Such comments help explain how a piece of code works.

Sphinx is a document generation tool for Python that is used to create project- and API-level documentations...