Python Library Reference is tutorial, not reference

A

aurora

Sometimes it is rather frustrated to use the Python Library Reference. It
seems each section is hand crafted and it is up to the author decide the
organization and coverage. For example the os module seems be broken down
in a somewhat abitrary way. You have to get use to it to find the way
around.

http://www.python.org/doc/2.3.4/lib/module-os.html

Some section, I would said, is more a tutorial than a reference. Most
frustrating is the material sometimes doesn't seem to be comprehensive.
For example, I was looking for reference on class cgi.FieldStorage. The
closet thing I found is some sample code in

http://www.python.org/doc/2.3.4/lib/node403.html

I have to look into source code to find all parameters accepted.

def __init__(self, fp=None, headers=None, outerboundary="",
environ=os.environ, keep_blank_values=0, strict_parsing=0):

Is Python going to adopt a more systematic organization of reference
materials, such as the once presented in:
http://epydoc.sourceforge.net/stdlib/public/cgi.FieldStorage-class.html
 
M

Michael Hoffman

aurora said:
Sometimes it is rather frustrated to use the Python Library Reference.

Personally, I like the current library reference, and wish it had more
example sections. They are usually the most helpful parts in my opinion.

Thanks for that link--seems very useful. If you like it so much, why
don't you just keep using that page? ;-) You could also submit a
documentation patch or RFE to get a link added to the python.org
documentation pages.
 
D

David Goodger

[aurora]
Sometimes it is rather frustrated to use the Python Library Reference.
It seems each section is hand crafted and it is up to the author decide
the organization and coverage.
.... many relevant examples omitted ...

You make some good points. It's true that Python's documentation is
not perfect.
Is Python going to adopt a more systematic organization of reference
materials,

Yes, if and only if someone puts in the effort.

Are you willing to do more than just complain? If so, please choose a
chapter and produce a patch. Assign it to me, and I'll make sure it
gets applied quickly -- if the patch is of good quality. After a few
patches, I'll recommend to python-dev that you be granted direct CVS
access, which would make the process that much more efficient.

--
David Goodger <http://python.net/~goodger>

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.4 (Darwin)
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org

iD8DBQFBcWGkrqIPjB1FxosRAsV1AKDddTb5zLX4eR2vtGWNAra2rhAXGwCdHDeX
wGYqUsVMm48X1CSkBBymQa4=
=1l7Z
-----END PGP SIGNATURE-----
 
J

Josiah Carlson

[Snip statements regarding Python's documentation not being great]

Having used (read and written) pydoc/javadoc-style documentation before,
I am personally not a big fan of them. I much prefer the conversational
and sometimes tutorial style of standard Python documentation, to an
arbitrary API reference. Sure, everyone writes documentation
differently, but you cannot expect one person to write all of the
documention.

With that said, I find reading the source to be very educational as to
how other people do things, but prefer to read /real/ source rather than
merely the interfaces to a particular module or class. If one had
access to a reasonably decent editor (Idle has this feature), one could
open the desired module very quickly and easily; perhaps even faster
than looking up the documentation. If one's editor had a heirarchical
listing of classes, functions, etc. (Idle also has this feature, though
it could be a bit better), the opening would produce pydoc-style
documentation on the fly.

Also considering that sites with pydoc documentation exist, would it be
sufficient for you if there were a link from every module page to its
equivalent pydoc reference?


- Josiah
 
C

Carlos Ribeiro

With that said, I find reading the source to be very
educational as to how other people do things, but
prefer to read /real/ source rather than merely the
interfaces to a particular module or class.

There's nothing like reading good source code to learn to program in
*any* language. However, there's something that pure source code don't
tell you, thats the *context* behind its design: the intentions, the
limitations (which may not be obivous), and the somewhat difficult
design choices faced by the programmer. For this, good comments are
important, but nothing beats good reference documentation. In my
opinion, it should not tell only what each function and argument does:
it should state how it is supposed to be used, and why does it make
sense.

As for complaining but not writing it myself... well, I really dont
feel comfortable doing that. English is not my native language, and
I'm afraid that the material that I write would not be good enough for
Python's documentation standard. It's one thing to post at c.l.py, and
another one to submit a documentation patch.


--
Carlos Ribeiro
Consultoria em Projetos
blog: http://rascunhosrotos.blogspot.com
blog: http://pythonnotes.blogspot.com
mail: (e-mail address removed)
mail: (e-mail address removed)
 
A

aurora

Having used (read and written) pydoc/javadoc-style documentation before,
I am personally not a big fan of them. I much prefer the conversational
and sometimes tutorial style of standard Python documentation, to an
arbitrary API reference.

Of course many documentations have good value. I just consider a
comprehensive apidoc is as a baseline reference is necessity and the
handwritten guide is a good complement. We can always look at source code
or use other tools like epydoc. But really a reference should be part of
the basic Python offering. This would be particular important to newcomers
who will use this as the primary reference.


Yes, if and only if someone puts in the effort.

Are you willing to do more than just complain? If so, please choose a
chapter and produce a patch. Assign it to me, and I'll make sure it
gets applied quickly -- if the patch is of good quality. After a few
patches, I'll recommend to python-dev that you be granted direct CVS
access, which would make the process that much more efficient.

I should huh. As this time I have a script to contribute. I just find out
about this pydoc module from you guys and it meet most of my need. I've
came up with this script to help launch it in a browser:



--pydocbr.py-------------------------------------------------------------
"""Usage: pydocbr.py [-p port]

Script to launch HTML pydoc in a web browser

options:
-h show this help
-p port number for the pydoc web server
default 7777
"""

import pydoc
import sys
import threading
import webbrowser

def usage():
print __doc__
sys.exit(-1)

def main():

port = 7777 # default port

if len(sys.argv) > 1:
if sys.argv[1] == '-h':
usage()
elif sys.argv[1] == '-p':
try: port = int(sys.argv[2])
except: usage()
else:
usage()

# launch the browser in 0.2s
browse = lambda: webbrowser.open("http://localhost:%d" % port)
threading.Timer(0.2, browse).start()

print 'Start serving pydoc at http://localhost:%d ...' % port
pydoc.serve(port)


if __name__ == '__main__':
main()
--------------------------------------------------------------------
 
?

=?ISO-8859-1?Q?Michael_Str=F6der?=

Josiah said:
Having used (read and written) pydoc/javadoc-style documentation before,
I am personally not a big fan of them. I much prefer the conversational
and sometimes tutorial style of standard Python documentation, to an
arbitrary API reference.

Me too.

Ciao, Michael.
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Members online

No members online now.

Forum statistics

Threads
473,733
Messages
2,569,440
Members
44,830
Latest member
ZADIva7383

Latest Threads

Top