On 07/07/2010 21:54, Georg Brandl wrote:
Am 07.07.2010 20:12, schrieb 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/
Yes, but: do we want this?
-1 :-)
I find those epydoc style framed API docs very hard to read and
navigate. On the other hand autogenerated API docs *can* be good looking
and usable.
Michael
Georg
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/fuzzyman%40voidspace.org.uk
--
http://www.ironpythoninaction.com/
http://www.voidspace.org.uk/blog
READ CAREFULLY. By accepting and reading this email you agree, on behalf of
your employer, to release me from all obligations and waivers arising from any
and all NON-NEGOTIATED agreements, licenses, terms-of-service, shrinkwrap,
clickwrap, browsewrap, confidentiality, non-disclosure, non-compete and
acceptable use policies (”BOGUS AGREEMENTS”) that I have entered into with your
employer, its partners, licensors, agents and assigns, in perpetuity, without
prejudice to my ongoing rights and privileges. You further represent that you
have the authority to release me from any BOGUS AGREEMENTS on behalf of your
employer.
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
