PEP257: Good Python docstrings by example

Following in the spirit of PEP 8, which is a style guide for Python code itself, the lesser-known PEP 257 establishes similar high-level conventions for docstrings. The module below attempts to illustrate by example. Hopefully this will be easier to grok than reading the PEP itself.

Wondering if you're own code is compliant with PEP 257? More than likely, you've been following several of these conventions simply by following the prevailing style of docstrings that you've encountered in the wild. Try using the pep257 package to validate your docstrings (similar to the pep8 tool) to take them the last mile:

$ pip install pep257

Usage:

I'd highly recommend using the --explain and --source options when you're just getting started. And maybe --ignore=D100,D101,D102,D103,D104 (see the full list of error codes here) to focus on polishing your existing docstrings before worrying about filling in the blanks.

Finally, if you've read this far and are convinced that you should tweak your docstrings accordingly, I'd recommend diving into PEP 257 itself. There's no better way to learn the finer points than going to the source of truth.