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 -- http://mail.python.org/mailman/listinfo/python-list