quickshotdevs team mailing list archive

[Luke-Jennings <ubuntujenkins@xxxxxxxxxxxxxx>]

On Mon, 2010-04-19 at 18:24 +0200, Vermeersch Simon wrote:
> On Sun, Apr 18, 2010 at 11:34 PM, Neil Tallim <red.hamsterx@xxxxxxxxx> wrote:
> > 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
> >
> 
> I don't have any preference for either, so whatever is most
> popular/well known is fine by me.
> 
> 

I don't have a preference, I have to learn which ever one we use so I
don't mind.

Luke