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

[Antoine Pitrou]

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.

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
>