Mailman 3 May 2000 - Doc-SIG

Nit in "urllib" library documentation
by Ka-Ping Yee Oct. 10, 2000

Oct. 10, 2000

See http://www.python.org/doc/1.5.2p2/lib/module-urllib.html The last chunk of the section on "urlopen" appears to be repeated twice: The urlopen() function works transparently with proxies... For example (the "%" is the command prompt): ... In a Macintosh environment, urlopen() will retrieve proxy information from Internet Config. The urlopen() function works transparently with proxies... For example (the "%" is the command prompt): ... In a Macintosh environment, urlopen() will retrieve proxy information from Internet Config. -- ?!ng

2 1

library reference contents
by Ka-Ping Yee Oct. 10, 2000

Oct. 10, 2000

The contents page of the Library Reference has a few warts: - A few section headers (e.g. operator, pprint, repr) end in periods that probably ought to be deleted. (Complete list: 3.5, 3.23, 3.24, 3.27, 3.32, 4.2, 4.3, 4.5, 5.10, 6.13, 6.15, 7.1, 7.6, 11.11, 11.12, 11.13, 12.13, 12.14, 14.9, 14.10, 15.4.) - Description of 3.28 "new" doesn't make much sense: "runtime implementation object creation" (probably you want to replace "implementation" with "instance") - Description of 4.3 "regex" should probably say "old" or "deprecated". - Description of 6.12 "curses" has a spelling mistake: "Terminal independant (sic) console handling". - Description of 7.14 "rlcompleter" probably ought to say "Completion function for GNU readline". - Descriptions of 11.14 "SimpleHTTPServer" and 11.15 "CGIHTTPServer" seem strange: "A Do-Something Request Handler". Suggest "11.14 SimpleHTTPServer -- A simple HTTP request handler" and "11.16 CGIHTTPServer -- A CGI-capable HTTP request handler". Hope this helps. -- ?!ng "I'm not trying not to answer the question; i'm just not answering it." -- Lenore Snell

2 1

Re: [Doc-SIG] htmldoc.py and inspect.py
by Juergen Hermann June 6, 2000

June 6, 2000

On Tue, 30 May 2000 02:43:54 -0700 (PDT), Ka-Ping Yee wrote: >I welcome your feedback! I'm currently using pdoc.py, and I will definitely will give your script a look. What I would like VERY much would be a Python doc system that shares as much as possible with the JavaDoc/DOC++/Doxygen world, especially the "commands" to provide semantic markup (like \param spam). Ciao, Jürgen -- Jürgen Hermann (jhe(a)webde-ag.de) WEB.DE AG, Amalienbadstr.41, D-76227 Karlsruhe Tel.: 0721/94329-0, Fax: 0721/94329-22

6 9

htmldoc.py and inspect.py
by Ka-Ping Yee May 30, 2000

May 30, 2000

Hi everyone. I'm writing to announce that i've posted my current work on a documentation generator. Those of you who were in the doc-sig room at IPC8 may remember the example i showed. Quite a few people seemed to like it and i promised to produce the script -- so here i am trying to make good on my promise. Done: - documentation of user modules, classes, methods, and functions - documentation of built-in functions - automatic hyperlinking when classes and methods are mentioned - detection of leading comments when no docstring is present - overview of class inheritance tree within a module - generation of HTML files from the command line - all generated files are SGML compliant! :) :) (HTML 4.0 Transitional) To do: - no directory/package indexing yet - simple HTTP server (so you can get fresh docs on your own modules) As there are still items on the to-do list it's not entirely done yet -- but there is enough done to work fairly well, and i wanted to give you a chance to look at it and let me know what you think. The modules are: http://www.lfw.org/python/htmldoc.py http://www.lfw.org/python/inspect.py Fred: i would like to seriously propose this to go with 1.6. Will you consider it? The "htmldoc" module is actually quite small (only about 300 lines) as most of the hard work has been factored out into the "inspect" module -- a non-HTML-specific collection of routines for getting all kinds of information out of your Python objects. My favourite routine in "inspect" is inspect.getsource(object), which can get you the source code for a function, method, or class. The IPC8 example i showed is at http://www.lfw.org/python/SocketServer.html That output was produced by a script called "manpy.cgi" that i wrote at work, and unfortunately that meant the script could not be distributed outside of my company. The new script produces very similar output, but it has been rewritten from scratch on my own time -- which means (a) it's completely unencumbered by any IP claims; and (b) i got to make it a little bit cleaner. I have run the new script over the Python 1.5.2 standard library. Please browse the results at http://www.lfw.org/python/htmldoc/ I welcome your feedback! Thanks, -- ?!ng "To be human is to continually change. Your desire to remain as you are is what ultimately limits you." -- The Puppet Master, Ghost in the Shell

3 4