← Back to team overview

quickshotdevs team mailing list archive

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