[AstroPy] Documentation Guidelines

Prasanth oneaufs at gmail.com
Mon Jul 11 00:06:33 EDT 2011


Hello,

One place the extra line can be useful is while writing docstrings that are
meant to be parsed by epydoc, in addition to Sphinx. So the guidelines can
be made flexible enough for incorporating both use cases.

Prasanth
On Mon, Jul 11, 2011 at 3:59 AM, Erik Tollerud <erik.tollerud at gmail.com>wrote:

> That format actually produces the exact same sphinx output as
>
> :param float v: Some desc.
>
> The advantage of the single line format is that in plain-text it's
> easier to read because it's only one entry for each parameter.  The
> disadvantage is that only a single-word plain text type is allowed -
> e.g. you can do neither ":param float or None v:", nor ":param
> :class:`AClass` v:". Separate ":param v:" and ":type v:"  allow any
> arbitrary sphinx markup to be used as a type. (those who are
> interested can see more details at
> http://sphinx.pocoo.org/markup/desc.html#info-field-lists)
>
> I have personally found that anytime I need more than a single-word
> type description, it ends up difficult to read (e.g. "v(float or int
> or array or None) - some desc." is harder to understand even in sphinx
> than "v - A thing that does this if it's a float, this if it's an int,
> this if it's an array, or this if None."  So it seems to me like the
> extra type line is *usually* unnecessary.
>
> On Sun, Jul 10, 2011 at 1:49 AM, Prasanth <oneaufs at gmail.com> wrote:
> > Hello,
> > The following format:
> >
> > :param v: Some desc.
> > :type    v: float
> > will create an output that looks something like
> > v(float) - Some desc.
> > in the Sphinx output. This also make it suitable for epydoc.
> > Similarly if we align the parameter names in all "param" and "type"
> fileds,
> > then it will be easier to read it as docstring in the terminal:
> > :param name1:
> > :type    name1:
> > :param n2:
> > :type    n2:
> > Prasanth
> > On Sun, Jul 10, 2011 at 11:56 AM, Erik Tollerud <erik.tollerud at gmail.com
> >
> > wrote:
> >>
> >> I (speaking just as myself rather than as a committee member) have
> >> generally used the following syntax, because it's easy to use with
> >> sphinx while remaining rather readable in plain-text.
> >>
> >> def func(arg1,arg2,**kwargs):
> >>    """
> >>    A one-sentence description of the function.
> >>
> >>    Possibly much longer discussion of the function.  This may
> >>    be multiple paragraphs. It can include sphinx markup, like
> >>    referencing the class :class:`AClass`.
> >>
> >>
> >>    :param int arg1: Describe the first parameter, an integer.
> >>    :param arg2:
> >>        Include a longer description here because this maybe
> >>        can be different types.
> >>    :param kwargs:
> >>        The function accepts additional arbitrary keywords,
> >>        which are passed into some other function.
> >>
> >>    :returns: Describe the return value here.
> >>    :except TypeError: Describe any exceptions here.
> >>
> >>
> >>
> >> On Sat, Jul 9, 2011 at 11:21 PM, Erik Tollerud <erik.tollerud at gmail.com
> >
> >> wrote:
> >> > As mentioned in the previous messages, I have added a wikispaces page
> >> > on the topic of documentation guidelines:
> >> >
> >> > http://astropy.wikispaces.com/Astropy+Documentation+Guidelines
> >> >
> >> > that page is obviously light on details, primarily because we (the
> >> > coordinating committee) want to solicit suggestions and opinions from
> >> > the list as to the best way to format docstrings.  This is the main
> >> > item that must be determined ASAP, because we expect people will be
> >> > writing docstrings as they start working on their code, and it's much
> >> > easier to agree on the docstring syntax beforehand than it is to go
> >> > back and fix it later.  The exact layout/style of the documentation is
> >> > probably less important right now, although I'm happy to entertain
> >> > discussion on that topic, as well.
> >> >
> >> > As we see it, the main goals for the function and class docstrings are
> >> > 1) readability in plain-text 2) clean-looking APIs when added to
> >> > sphinx documentation.  Any suggestions for preferred formats?
> >> >
> >> > --
> >> > Erik Tollerud
> >> >
> >>
> >>
> >>
> >> --
> >> Erik Tollerud
> >> _______________________________________________
> >> AstroPy mailing list
> >> AstroPy at scipy.org
> >> http://mail.scipy.org/mailman/listinfo/astropy
> >
> >
>
>
>
> --
> Erik Tollerud
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/astropy/attachments/20110711/f7c9f20e/attachment.html>


More information about the AstroPy mailing list