On Sat, Mar 27, 2010 at 7:44 AM, Vinzent Steinberg
<vinzent.steinb...@googlemail.com> wrote:
> On Mar 27, 9:35 am, Toon Verstraelen <toon.verstrae...@ugent.be>
> wrote:
>> Hello,
>>
>> I would like to update the docstrings for the printer module somewhere
>> in the future, but there does not seem to be a real consensus or
>> convention on how to format docstrings in SymPy. Especially formatting
>> the arguments of functions and methods is done in many different ways.
>>
>> I've used this format before for functions (not in SymPy) and it is a
>> reasonable compromise between readability in html, compactness and
>> readability of the docstring as plain text:
>>
>> def foo(a, b, c=3):
>> """Summary that fits on one line.
>>
>> Some more multiline text with important info regarding this
>> function. (still condensed, one paragraph)
>>
>> Arguments:
>> | ``a`` -- Some argument with a lot of explanations that do
>> not all fit on one line. The vertical bar relaxes
>> the restructured text indentation sensitivity,
>> | ``b`` -- Another argument.
>>
>> Optional argument:
>> | ``c`` -- Describe optional argument c. [default=3]
>>
>> Some more multiline text with less important but nevertheless
>> interesting info on this function. Usage examples etc. Can be
>> more than one paragraph.
>> """
>>
>> I used to be reluctant towards such verbose docstrings, but It is a
>> life-saver for people that are new to the code, or also when you haven't
>> worked with certain code for a few year.
>>
>> For the documentation of constructors, there is an option in
>> doc/src/conf.py:
>>
>> autoclass_content = "both"
>>
>> It includes the __init__ docstring in the documentation of the class.
>> Something along these lines is again a reasonable compromise:
>>
>> class Bar(object):
>> """One line summary.
>>
>> Multiline text with important info about the class. (still
>> condensed, one paragraph)
>> """
>> def __init__(a, b, c=3):
>> """
>> Arguments:
>> | ``a`` -- Some argument with a lot of explanations that do
>> not all fit on one line.
>> | ``b`` -- Another argument.
>>
>> Optional argument:
>> | ``c`` -- Describe optional argument c. [default=3]
>>
>> Some more multiline text with less important but nevertheless
>> interesting info on this class. Usage examples etc. Can be
>> more than one paragraph.
>> """
>>
>> Any suggestions to improve this format? When we come to a consensus, I'm
>> happy to explain it in the section 'How to Write Docstrings'.
>>
>> cheers,
>>
>> Toon
>
> I like mpmath's format:
>
> **Arguments**
> *arg1*
> description
> *arg2*
> description
Note that each docstring must (should) contain examples of usage of
the function.
I like this way:
def f(x):
"""
First line.
Some more textlkja sd;lkfj aslfj asl;fdj
a;lsdfjal;kskfj lasjdfla;sdkfj
Examples:
>>> x**2
x**2
""""
Notice the indentation, it seems compatible with Python, and also Sage.
Ondrej
--
You received this message because you are subscribed to the Google Groups
"sympy" group.
To post to this group, send email to sy...@googlegroups.com.
To unsubscribe from this group, send email to
sympy+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/sympy?hl=en.
