[AstroPy] Documentation Guidelines

Prasanth oneaufs at gmail.com
Sun Jul 10 04:49:04 EDT 2011


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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/astropy/attachments/20110710/908eb79a/attachment.html>


More information about the AstroPy mailing list