Python Documentation (should be better?)

[Sébastien Boisgérault]

Christopher J. Bottaro wrote:
> [...]
> Funny, the con of Python (documentation) is PHP's strong point.
> The PHP manual is extremely easy to navigate and its search feature
> works great. Contrast that with Python, where you have to use "the
> tutorial" as the manual.  Also, the tutorial is just that...a
tutorial,
> its a NOT a manual.

The tutorial is great IMHO and yes, it is definitely not a
reference guide. But what's wrong with the online library
reference or its pdf equivalent ? And why don't you use the
python.org "search" (top right of the screen) ?

> Now for the real kicker.  Some of the module documentation doesn't
> even list simple use cases or even the entire API.

Sometimes the 'missing' interface is (superficially) hidden
on purpose. Example in doctest about the DocTestCase class
(quoted from the library ref) :

"""
Under the covers, DocTestSuite() creates a unittest.TestSuite out of
doctest.DocTestCase instances, and DocTestCase is a subclass of
unittest.TestCase. DocTestCase isn't documented here (it's an internal
detail), but studying its code can answer questions about the exact
details of unittest integration.
"""

Could you be more specific about the modules/packages
that lack proper examples/documentation ?

> When my coworker came to me with
> this complaint, my response was "oh, just load the interpreter,
> import the module and call dir() on it.  Then instantiate some
objects
> and call dir() on them also".  My infatuation with Python had kept me

> from realizing the sheer ridiculousness of that method to learn to
> use an API.  Needless to say, my coworker's reaction to that
statement
> snapped me out of it.  But its the truth.  How many of you learn a
> module by starting the interpreter
> and "playing" around with it and using dir()?

You may also use "help" instead of "dir", or directly
pydoc in a shell:

python>>> help("math")
python>>> help(math) # if 'math' has already been imported
bash$ pydoc math

This kind of documentation system suits me (it is far better
than a raw dir anyway). It supports a 'dotted reference'
description of the path to the objects (ie
package.subpackage.module.holder.object) that is IMHO very
convenient.

Cheers,

SB