[Python-Dev] query: docstring formatting in python distutils code

[Brett Cannon]

On Wed, Jul 7, 2010 at 11:46, Antoine Pitrou <solipsis at pitrou.net> wrote:
> On Wed, 7 Jul 2010 14:12:17 -0400
> Barry Warsaw <barry at python.org> wrote:
>> On Jul 07, 2010, at 07:30 PM, Georg Brandl wrote:
>>
>> >Overall, I think that we can make stdlib docstrings valid reST -- even
>> >if it's reST without much markup -- but valid, so that people pulling
>> >in stdlib doc- strings into Sphinx docs won't get ugly warnings.
>> >
>> >What I would *not* like to see is heavy markup and Sphinx specifics --
>> >that would only make sense if we included the docstrings in the docs,
>> >and I don't see that coming.
>>
>> Does it make sense to add (reST-style) epydoc markup for API signatures?
>> E.g.
>
> It really looks ugly (and annoying to decipher) when viewed in plain
> text.

I agree. And it is highly repetitive since the signature information
is right there already. All of that info in those annotations can
easily be written in paragraph form if needed and honestly would read
better to my eyes.

-Brett

>
> Regards
>
> Antoine.
>
>
>>
>> def create_foo(name, parent=None):
>>     """Create the named foo.
>>
>>     The named foo must not already exist, but if optional `parent` is given,
>>     it must exist.
>>
>>     :param name: The name of the new foo.
>>     :type name: string
>>     :param parent: The new foo's parent.  If given, this must exist.
>>     :type parent: string
>>     :return: The new foo.
>>     :rtype: `Foo`
>>     :raises BadFooNameError: when `name` is illegal.
>>     :raises FooAlreadyExistsError: when a foo with `name` already exists.
>>     :raises BadParentError: when the foo's parent does not exist.
>>     """
>>
>> We could then generate automatic API docs from this, a la:
>>
>> http://www.blender.org/documentation/248PythonDoc/
>>
>> -Barry
>>
>
>
> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: http://mail.python.org/mailman/options/python-dev/brett%40python.org
>