[AstroPy] Documentation Guidelines

[Erik Tollerud]

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