Preferred syntax for the docstrings

[Chris Rebert]

On Thu, Mar 19, 2009 at 6:26 AM, Luis Zarrabeitia <kyrie at uh.cu> wrote:
>
> What's the preferred style to document code in python? I usually do something
> like this:
>
> ===
> def somefunction(arg1, arg2, out = sys.stdout):
>    """ This function does blahblablha with the string arg1, using
>    the tuple of ints arg2 as the control sequence, and prints the
>    result to out (defaults to sys.stdout) """
> ===
>
> That seems sub-optimal, I can't rapidly see what are you expecting from the
> arguments or the return value. I've seen some docstrings with the style
>
> ===
> def somefunction(arg1, ar2, out = sys.stdout):
>    """ brief description, possibly involving <some symbol>arg1, <some symbol>
>        arg2 and <some symbol> arg3>
>        <some symbol> arg1: string, some description
>        ...
>    """
> ===
>
> I guess there are several languages for writing the docstring. The question is,
> which is the preferred one in python, and where can I learn the syntax? (the one
> that python documentation viewers understand better? the one used by the
> stdlib?) How should/in what order should I write the docs? (brief description,
> argument types, return type, followed perhaps by some doctests).

It's pretty subjective based on which documentation generator you use
(or if you don't use one at all, just your personal style), but
personally I'd recommend reStructuredText and Sphinx
(http://sphinx.pocoo.org/) since they're used for the std lib's very
spiffy new docs. See the Sphinx homepage for how to learn the syntax.

Cheers,
Chris

-- 
I have a blog:
http://blog.rebertia.com