Python docs disappointing

[Chris Rebert]

> On Fri, Jul 31, 2009 at 1:10 PM, kj <no.email at 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<suruti94 at 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