[AstroPy] Documentation Guidelines

[Erik Tollerud]

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