7.8 Documenting Python code

A docstring is a free-standing string surrounded by three double quotes that describes what your code does.

Developers read the docstrings when browsing your code. By their location, Python associates docstrings with your modules, classes, functions, and methods. Python collects the docstrings and makes them available to your code’s users via functions like help. Third-party tools like Sphinx can process your code to create beautiful web and PDF documents for your users’ reference. [SPH]

One of the most popular Python documentation conventions is part of the Google Python Style Guide. [GSG, Section 3.8] To add lightweight markup for formatting, many coders use “reStructuredText” within their docstrings. [RST] The NumPy and SciPy package developers combined and tweaked these into the “numpydoc docstring guide.” I use their conventions...