Mailman 3 May 1998 - Doc-SIG

RE: gendoc bug
by Daniel Larsson May 25, 1998

May 25, 1998

I've uploaded a fixed version of gendoc (0.73) that doesn't use the obsolete 'codehack' module. Thanks Lars! -----Original Message----- From: unknown@BIRK105 [mailto:unknown@BIRK105]On Behalf Of Lars Marius Garshol Sent: den 25 maj 1998 14:23 To: Daniel Larsson Subject: gendoc bug Hi! I just installed gendoc 0.72 and tried to run it on two of my programs. In both cases it threw an ImportError on line 121 (in _funline) of doc_collect.py, claiming that the module codehack does not exist. As far as I can see, this is correct, since no file named codehack* is in either the gendoc or Python 1.5.1 distributions. Very nice if you can fix this. Thanks! -- "These are, as I began, cumbersome ways / to kill a man. Simpler, direct, and much more neat / is to see that he is living somewhere in the middle / of the twentieth century, and leave him there." -- Edwin Brock http://www.stud.ifi.uio.no/~larsga/ http://birk105.studby.uio.no/

1 0

Re: [Doc-SIG] gendoc 0.71 patch
by Mark Hammond May 23, 1998

May 23, 1998

>We (mostly Robin Friedrich and I) started talking about a major >facelift to gendoc, basically making it much more layered, which >would help a lot in doing what you're after. I don't know, maybe >the docstring should be represented more like a XML DSO? And dont forget that I have promised to hassle and help on making sure that these changes support decent cross-references. We even have the syntax all nutted out :-) Mark.

2 1

gendoc 0.71 patch
by Andrew Kuchling May 21, 1998

May 21, 1998

I grabbed a copy of gendoc 0.71 this weekend in order to look at adding a TeX formatter, and found I had to make various changes just to get things to work. Patch included below. My motivation for adding a TeX formatter is for the ongoing XML work; some of it has very good docstrings which could make up the docs, so I'd like to modify gendoc to output LaTeX code suitable for the Library Reference (or similar documents such as HOWTOs). Adding TeX output that uses '\code{' and '}' instead of '<code>' and '</code>' wasn't difficult, but the output doesn't look anything like the usual docs because the structure is different; there are things like \section SYNOPSIS, instead of \section{gendoc module}. The document structure hard-wired into the code is different from that in the LaTeX docs. Any suggestions about the approach that should be taken to fix this? There are smaller issues; in LaTeX we want to do more detailed markup, such as \class{Message} and \function{input()}, but perhaps that will have to be left to manual editing afterwards. -- A.M. Kuchling http://starship.skyport.net/crew/amk/ Ambition has but one reward for all: / A little power, a little transient fame, A grave to rest in, and a fading name. -- William Winter diff -r -C2 /scratch/gendoc/formatters/Formatters.py gendoc/formatters/Formatters.py *** /scratch/gendoc/formatters/Formatters.py Wed Feb 4 09:19:42 1998 --- gendoc/formatters/Formatters.py Sun May 10 10:18:01 1998 *************** *** 141,145 **** def main(path): ! files = reduce(lambda c, dir: c+os.listdir(dir), path, []) modules = filter(lambda file: file[-3:] == '.py', files) --- 141,146 ---- def main(path): ! files = os.listdir(path+"") ! # files = reduce(lambda c, dir: os.listdir(c+dir), path, []) modules = filter(lambda file: file[-3:] == '.py', files) diff -r -C2 /scratch/gendoc/formatters/MIFFormatter.py gendoc/formatters/MIFFormatter.py *** /scratch/gendoc/formatters/MIFFormatter.py Wed Feb 4 10:16:38 1998 --- gendoc/formatters/MIFFormatter.py Sun May 10 10:19:18 1998 *************** *** 63,67 **** import string import regsub ! from gendoc import docregex # Rename imported objects. --- 63,67 ---- import string import regsub ! import docregex # Rename imported objects. Only in gendoc/formatters: TeXFormatter.py diff -r -C2 /scratch/gendoc/formatters/__init__.py gendoc/formatters/__init__.py *** /scratch/gendoc/formatters/__init__.py Wed Feb 4 07:03:38 1998 --- gendoc/formatters/__init__.py Sun May 10 10:44:50 1998 *************** *** 1,2 **** import Formatters ! Formatters.main(__path__) --- 1,2 ---- import Formatters ! Formatters.main(__path__[0]) diff -r -C2 /scratch/gendoc/gendoc gendoc/gendoc *** /scratch/gendoc/gendoc Wed Feb 4 03:16:26 1998 --- gendoc/gendoc Sun May 10 10:17:42 1998 *************** *** 7,9 **** import gendoc.gendoc ! gendoc.gendoc.main() --- 7,9 ---- import gendoc.gendoc ! gendoc.gendoc.main_parseopts() diff -r -C2 /scratch/gendoc/gendoc.py gendoc/gendoc.py *** /scratch/gendoc/gendoc.py Wed Apr 1 03:59:40 1998 --- gendoc/gendoc.py Sun May 10 10:36:35 1998 *************** *** 164,167 **** --- 164,168 ---- # Process command line arguments try: + if len(sys.argv) == 1: raise getopt.error, "No arguments provided" optlist, args = getopt.getopt(sys.argv[1:], '?ipuvd:h:f:') except getopt.error, str: *************** *** 192,206 **** include_private_methods = 1 elif opt[0] == '-f': ! try: ! formats.append(Formatters.formatters[opt[1]]()) ! except KeyError, key: ! print "Couldn't find a %s formatter (is it in the formatters subdir?)" % key ! frmtrs = reduce(lambda c, i: c+', '+i, Formatters.formatters.keys()) ! print "Valid formatters are:", frmtrs ! sys.exit(0) ! if not formats: ! formats = [Formatters.formatters['HTML']()] # Arguments in the '<key>=<value>' style are stripped, and stored in --- 193,200 ---- include_private_methods = 1 elif opt[0] == '-f': ! formats.append( opt[1] ) if not formats: ! formats = ['HTML'] # Arguments in the '<key>=<value>' style are stripped, and stored in *************** *** 231,235 **** main(args, formats, head, parse, VERBOSE) except GendocException, x: - import sys sys.stderr.write(x) sys.exit(0) --- 225,228 ---- *************** *** 336,340 **** import parser except: - import sys sys.stderr.write('You must include the parser module in your Setup\n') sys.stderr.write('to run in parser mode!\n') --- 329,332 ---- *************** *** 352,356 **** ast_tuple = parser.ast2tuple(parser.suite(text)) except: - import sys sys.stderr.write("Sorry, got a syntax error when parsing %s\n" % file) --- 344,347 ---- *************** *** 420,424 **** file = open(os.path.join(directory, filename), 'w') except IOError, str: - import sys sys.stderr.write("%s: %s" % (os.path.join(directory, filename), str)) sys.exit(1) --- 411,414 ---- *************** *** 430,432 **** if __name__ == '__main__': ! main() --- 420,422 ---- if __name__ == '__main__': ! main_parseopts()

2 3

Re: [Doc-SIG] gendoc 0.71 patch
by Robin Friedrich May 21, 1998

May 21, 1998

Tried 0.72 last night and it works MUCH better now. Thanks again Daniel!

1 0

New directory layout for Python documentation tree
by Fred L. Drake May 19, 1998

May 19, 1998

I've worked on the layout of the Python documentation tree a little; the top level is a little (!) less cluttered. In particular, it now looks like this: Doc/ api/ # individual documents ext/ lib/ mac/ ref/ tut/ icons/ # utilities/tool support stuff perl/ texinputs/ tools/ html/ # output areas api/ ext/ lib/ mac/ ref/ tut/ info/ paper-a4/ paper-letter/ The Makefile at the top level has changed a lot (probably not enough), but the main targets all seem to work just fine. Formatting for A4 paper can be done just by using "make PAPER=a4" instead of "make"; the paper-related output will automatically end up in the appropriate paper-*/ directory (.dvi, .pdf, and .ps). I'd like interested people to try out the new directory layout and tool changes to see if there are any problems that I've not been able to identify. I'm also interested in whether any additional flexibility is needed in the build process. Note that the process requires a fairly substantial LaTeX installation and the latest release of latex2html; see the README for specific information on the versions we're using and where to get them. I've placed a number of tarballs on ftp.python.org in the directory pub/python/doc/testing/. If your interested in trying out the new tree and process changes, please download the sources tarball (latex-1.5.1-testing.tgz), read the README, and give it a whirl. The other tarballs are the output I get, and (big disclaimer here) may not reflect the actual state of any Python release. Yes, there are changes here that relate to the development version of Python, so please don't rely on the documents themselves. (Ok, the changes that don't apply to the release versions are very small.) I'm very interested in feedback, so please give it a try if you can and let me know if you have any problems with the process or concerns about the new layout of the tree. -Fred -- Fred L. Drake, Jr. fdrake(a)cnri.reston.va.us Corporation for National Research Initiatives 1895 Preston White Drive Reston, VA 20191

1 0

Missing documentation in os module?
by Kevin J. Butler May 14, 1998

May 14, 1998

A recent proselyte (not yet a convert) asked how to walk directories in Python. I told him about os.listdir and os.path.isdir, and then os.path.walk, and directed him to the library reference, os module section. Turns out, that section doesn't document these functions (or a bunch of other functions in the os module). I think it used to--or did I learn about them somewhere else? Is there a problem in the conversion to HTML? Also, I knew to look in posixpath for path functions, but there wasn't a reference to NT functionality that a novice could find... kb -- Kevin Butler butler(a)byu.edu 8-) A pun a day keeps the doctor away...and everyone else, too. http://students.cs.byu.edu/~butler/homepage.html (updated 10/18/96)

2 1