I'm a new python user (developing in python) and I recently had a
discussion with someone that my main issue with python is finding where
the functions are that I need to use.

An example (probably not the best) - I need to split a filename so that
I can have the extension and the rest of the filename seperate. Fine.. I
google, and I get the following page:-

http://www.python.org/doc/2.5.2/lib/os-path.html

Now, that lists the function splitext - which is what I need - but it's
not clear on the page where that function is located (os.path) 

I think that this should be made clearer somehow - as it seems to me
that you have to go through about 3 pages trying to work out where it is
(or work it out from the URL) - which isn't very intuitive, espescially
for a new user, who doesn't actually know where all the functions exist.

What would be helpful would be a specific suggestion from the OP (or, better still, a doc patch) as to exactly what should change or at least what kind of words should go where. As it stands, this report highlights a real but quite general issue issue but doesn't take us anywhere towards how we could improve things.

Well, I can't offer a patch (as I said - I'm a python n00b) - but I can
offer suggestions.

1) show the functions as where they are - for example - splitext would
be shown as os.path.splitext(arguments)

2) header titles for groups within the same module. So splitext, etc
etc, would be under a visible title that says "os.path"

3) alternate documentation links by modules. So the documentation stays
the same, but there is also an alternate set which shows the same
things, but where the "up" button would take me from os.path to os
(showing that that is the module title) rather than the title being 
14.1.6 Miscellaneous System Information 

In fact - 3 exists - sort of, it just seems a little wrong.

Link 1: http://www.python.org/doc/2.5.2/lib/os-path.html
Title: 
14.1.6 Miscellaneous System Information 
How to get there:- Python Library Reference -> Generic Operating System
Services -> os -> Miscellaneous System Information 

Link 2: http://www.python.org/doc/2.5.2/lib/module-os.path.html
Title: 11.1 os.path -- Common pathname manipulations 
How to Get there:- Python Library Reference -> File and Directory Access
->  os.path -- Common pathname manipulations 

Link 2 seems to give the information in a good way - but didn't show on
my "quickly search google" radar. Plus, the way to get there seems
wrong. It should (IMO) be accessible through "Python Library Reference
-> modules -> os -> os.path" or something similar.

Did you see that the current (=2.6) documentation has changed a lot?
For example:

http://docs.python.org/library/os.path.html#os.path.splitext

It seems that most of your concerns have been addressed. (also, see the
nice URL)
I suggest that you try it, and address your recommendations from there.

Like Amaury said, I think this is fixed.

Yes, the new docs are much better.  Methods are nicely identified in
2.6/3.0 docs that I checked.  There is one category that is not:
constants.  For instance, the following is from the subprocess doc.

"stdin, stdout and stderr specify the executed programs’ standard input,
standard output and standard error file handles, respectively. Valid
values are PIPE, an existing file descriptor (a positive integer), an
existing file object, and None. PIPE indicates that a new pipe to the
child should be created. With None, no redirection will occur; the
child’s file handles will be inherited from the parent. Additionally,
stderr can be STDOUT, which indicates that the stderr data from the
applications should be captured into the same file handle as for stdout."

As I discovered, neither 'PIPE' nor PIPE is valid, subprocess.PIPE is
what is required.  (Ditto for subprocess.STDOUT I presume.) Can such
names of constants be fully qualified just as method names are now?

You are quite right. I've given PIPE and STDOUT their own entries now in
r67608.