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
Vinzent
--
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.
