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

[Barry Warsaw]

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.

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: not available
URL: <http://mail.python.org/pipermail/python-dev/attachments/20100707/7a1724f2/attachment.pgp>