Python Library Reference is tutorial, not reference

[aurora]

On Sat, 16 Oct 2004 14:38:17 -0700, Josiah Carlson <jcarlson at uci.edu>  
wrote:
> 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.


On Sat, 16 Oct 2004 13:59:58 -0400, David Goodger <goodger at python.org>  
wrote:
>
> 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()
--------------------------------------------------------------------