[Python-Dev] query: docstring formatting in python distutils code (original) (raw)

Antoine Pitrou solipsis at pitrou.net
Wed Jul 7 20:46:11 CEST 2010

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 createfoo(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

More information about the Python-Dev mailing list