While inline comments and type notations are useful for developers who will be working on the code base, external parties need more extensive documentation, and need it in a more attractive format than reading the source (this is especially true when they do not have access to the source). This need for documentation must be balanced against the understandable reluctance of developers to spend a great deal of time and energy producing anything but code.

Python's solution is to employ a lightweight markup language, reStructuredText, and a toolchain (Docutils, Sphinx) to transform reStructuredText into a more aesthetically attractive format (for example, HTML or LaTeX).

Aesthetics are not everything, however. Documentation must contain useful information in order to be worth using. Various guidelines (PEP 0008, PEP 3107, PEP 0484, PEP 0257, Google, NumPyDoc, and others) have come into being to provide advice. A production project should settle for a set of guidelines before coding starts...