Python Documentation (should be better?)

[Christopher J. Bottaro]

Steven Bethard wrote:

> Ivan Van Laningham wrote:
>> The Python docs are not ideal.  I can never remember, for instance,
>> where to find string methods (not methods in the string module, but
>> methods with '')
> 
> Hmmm... Well going to http://docs.python.org/ and typing "string
> methods" into the search box gives, as the first hit:
> 
> http://docs.python.org/lib/string-methods.html
> 
> Even if you just search for "string", that URL is the second hit, and
> pretty clearly the right one from the title.
> 
> STeVe

Heh, searching "dict methods" didn't produce the correct results on the
first page.  "dictionary methods" did.  searching for "append" returned the
array's module page as the first result, and list's module page as the 8th
result.  Search for "static" came up with nothing.  Search for
"staticmethod" came up with the built-in-funcs page, from which I had to
search again for "staticmethod".

The search mechanism isn't all that great (imo anyways).  Honestly, neither
is the PHP one, except when you are only searching the function list.  Then
its the bomb.  I also like how each PHP function gets its own page and each
page is full of examples.  And I love how each page shows related
functions.  Granted its easier to do the function list search for PHP
because there are no namespaces or classes, but still I think Python could
do something similar.  Say for instance search for "append" and it will
come back with a page for list's append, a page for array's append, etc.

My idea for a manual's table of contents:

1.  Variables
2.  Conditional and Branching Constructs
3.  Looping Constructs
4.  Functions
5.  Modules
6.  Classes
7.  Exceptions
8.  Built-in
   8.1  Functions
   8.2  Types

Of course there should be more detailed sublevels.  The tutorial (at least
chapters 3-11) make a good (partial) manual.  I think those chapters should
be the basis for a real manual vs. a tutorial.

If I wanted to learn about "types" in Python, where do I look?  The PHP
manual has a whole section on the built-in types, how to get the type of a
var, how to change cast the type of a var, etc.  I think that is such an
important and basic part of any language, yet its scattered all over Python
documention, difficult to find (i.e. not in a manual, but the library
reference).

I guess what I'm trying to say is that there should be a "manual" which is
half way between the tutorial and the library reference, that is organized
more like a traditional manual (whatever that means, right?) and is more
easily searchable.

-- C