> On Fri, Jul 31, 2009 at 1:10 PM, kj <no.em...@please.post> wrote: >> I'm pretty new to Python, and I like a lot overall, but I find the >> documentation for Python rather poor, overall. >> >> I'm sure that Python experts don't have this problem: they have >> internalized some good ways to access the documentation, are >> productive with it, and therefore have lost the ability to see why >> the Python documentations is deficient for beginners. This explains >> why a suboptimal situation can persist like this: those who are >> most able fix it are also the least able to perceive it. >> >> I've heard similar complaints from other experienced programmers >> who are trying out Python for the first time: poor documentation. >> >> Here is an *entirely typical* example: on some Unix, try >> >> % pydoc urllib >> >> The displayed documentation mention the optional parameter "data" >> in practically every function listed (a few dozen of them). This >> parameter is not documented *anywhere* on that page. All that we >> are told is that its default value is always None. >> >> I'm sure that I can find a full description of this parameter if >> I fire up Google, and search online. In fact, more likely than >> not, I'll find far more documentation than I want. But my point >> is that a programmer should not need to do this. The full >> documentation should be readily accessible directly through a few >> keystrokes. >> >> I would love to know how experienced Python programmers quickly >> zero in on the Python documentation they need. On Sun, Aug 2, 2009 at 4:22 PM, Mohan Parthasarathy<surut...@gmail.com> wrote: > I am a newbie and about a month old with Python. There is a wealth of > material about Python and I am really enjoying learning Python. > > One thing that could have helped Python documentation is that instead of the > very "raw" doc string, it could have used something like PythonDoc (java doc > style) so that the functions/classes are documented better. At least I am > planning to use PythonDoc for the code that I am going to write. Let me know > if there is a better one..
If you use reStructuredText (http://docutils.sf.net/rst.html), you can leverage Sphinx (http://sphinx.pocoo.org/), which generates the superb-looking official Python docs. Cheers, Chris P.S. Please don't top-post (http://en.wikipedia.org/wiki/Top-post) in the future. -- http://blog.rebertia.com -- http://mail.python.org/mailman/listinfo/python-list
