PEP 257 outlines what wording should be used in a docstring (e.g. say return, not returns), but not how it should be formatted. I was initially going to use the reST format (because sphinx - a python documentation generator - can read that), but it's not the most human readable format. Instead, I'm going to follow the suggestion on this stack overflow post and follow the Google Python Style Guide, which the next version of sphinx will support. A good example of the format is here.
PEP 257 outlines what wording should be used in a docstring (e.g. say return, not returns), but not how it should be formatted. I was initially going to use the reST format (because sphinx - a python documentation generator - can read that), but it's not the most human readable format. Instead, I'm going to follow the suggestion on this stack overflow post and follow the Google Python Style Guide, which the next version of sphinx will support. A good example of the format is here.