[AstroPy] Documentation Guidelines
erik.tollerud at gmail.com
Sun Jul 10 02:26:32 EDT 2011
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.
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.
Include a longer description here because this maybe
can be different types.
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:
> 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
More information about the AstroPy