This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: Python Documentation not Newb Friendly
Type: enhancement Stage:
Components: Documentation Versions:
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: georg.brandl Nosy List: amaury.forgeotdarc, georg.brandl, mez, terry.reedy, tim.golden
Priority: normal Keywords:

Created on 2008-12-02 14:38 by mez, last changed 2022-04-11 14:56 by admin. This issue is now closed.

Messages (7)
msg76747 - (view) Author: Martin Meredith (mez) Date: 2008-12-02 14:38
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:-

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.
msg76749 - (view) Author: Tim Golden (tim.golden) * (Python committer) Date: 2008-12-02 14:50
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.
msg76751 - (view) Author: Martin Meredith (mez) Date: 2008-12-02 15:31
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:
14.1.6 Miscellaneous System Information 
How to get there:- Python Library Reference -> Generic Operating System
Services -> os -> Miscellaneous System Information 

Link 2:
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.
msg76756 - (view) Author: Amaury Forgeot d'Arc (amaury.forgeotdarc) * (Python committer) Date: 2008-12-02 16:26
Did you see that the current (=2.6) documentation has changed a lot?
For example:

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.
msg76757 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-12-02 16:29
Like Amaury said, I think this is fixed.
msg77081 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2008-12-05 22:14
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?
msg77115 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-12-06 11:57
You are quite right. I've given PIPE and STDOUT their own entries now in
Date User Action Args
2022-04-11 14:56:41adminsetgithub: 48738
2008-12-06 11:57:51georg.brandlsetstatus: pending -> closed
messages: + msg77115
2008-12-05 22:14:13terry.reedysetnosy: + terry.reedy
messages: + msg77081
2008-12-02 16:29:23georg.brandlsetstatus: open -> pending
resolution: fixed
messages: + msg76757
2008-12-02 16:26:44amaury.forgeotdarcsetnosy: + amaury.forgeotdarc
messages: + msg76756
2008-12-02 15:31:34mezsetmessages: + msg76751
2008-12-02 14:50:45tim.goldensetnosy: + tim.golden
messages: + msg76749
2008-12-02 14:38:26mezcreate