[AstroPy] Documentation Guidelines
erik.tollerud at gmail.com
Sun Jul 10 18:29:55 EDT 2011
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
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:
> 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:
> On Sun, Jul 10, 2011 at 11:56 AM, Erik Tollerud <erik.tollerud at gmail.com>
>> 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>
>> > 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
More information about the AstroPy