quickshotdevs team mailing list archive
-
quickshotdevs team
-
Mailing list archive
-
Message #00133
Standard docstring format
There are two major Python documentation formats, and we kinda need to
pick one so that our code can have a consistent look and
auto-generated documentation.
Epytext (http://epydoc.sourceforge.net/manual-epytext.html)
Personally, this is my preference. It's flexible, produces
great-looking documentation, and allows everything to be described,
without ambiguity.
reStructuredText
(http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html)
This is more commonly found in the Python community, since it strikes
the sweet spot between depth of information, quality of presentation,
and effort.
My vote's for Epytext, but I work with reStructuredText enough to not
mind switching.
Also, regarding the docstrings themselves, I like the three-line
format most, for consistency, rather than brevity.
def xyz():
"""
This is how I'd write a one-line docstring.
"""
pass
Post your comments and we'll go with whatever seems most popular.
-Neil
Follow ups