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 at 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.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4