From akuchlin@cnri.reston.va.us Mon May 11 14:56:10 1998 From: akuchlin@cnri.reston.va.us (Andrew Kuchling) Date: Mon, 11 May 1998 09:56:10 -0400 (EDT) Subject: [Doc-SIG] gendoc 0.71 patch Message-ID: <13655.320.1586.637228@newcnri.cnri.reston.va.us> 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 '

' and
'

' 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 '=' 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 '=' 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() From butler@cs.byu.edu Wed May 13 15:21:39 1998 From: butler@cs.byu.edu (Kevin J. Butler) Date: Wed, 13 May 1998 08:21:39 -0600 (MDT) Subject: [Doc-SIG] Missing documentation in os module? Message-ID: 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@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) From Fred L. Drake, Jr." References: Message-ID: <13659.2346.261405.305297@weyr.cnri.reston.va.us> Kevin J. Butler writes: > 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... Kevin, Sorry for the delay; I'm not ignoring your question! General swampage is getting in the way a little. ;-( The posixpath module is the best reference for os.path at this time; I don't recall any other reference material for this. There might be something in one of the books, however. Hopefully this material will be easier to locate in a future version of the library reference, but I don't know quite what form it should take yet. -Fred -- Fred L. Drake, Jr. fdrake@cnri.reston.va.us Corporation for National Research Initiatives 1895 Preston White Drive Reston, VA 20191 From Fred L. Drake, Jr." 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@cnri.reston.va.us Corporation for National Research Initiatives 1895 Preston White Drive Reston, VA 20191 From Daniel.Larsson@vasteras.mail.telia.com Wed May 20 20:26:57 1998 From: Daniel.Larsson@vasteras.mail.telia.com (Daniel Larsson) Date: Wed, 20 May 1998 21:26:57 +0200 Subject: [Doc-SIG] gendoc 0.71 patch In-Reply-To: <13655.320.1586.637228@newcnri.cnri.reston.va.us> Message-ID: <000201bd8425$4122d4a0$94bd43c3@Daniel.telia.com> Hi Andrew, FYI, I've uploaded a new version (0.72) on my starship account (http://starship.skyport.net/crew/danilo). I've fixed a number of problems (0.71 was totally crappy...). Hmm, I see now that I forgot some of your changes. There will be a 0.73, obviously :-) -----Original Message----- From: Andrew Kuchling [mailto:akuchlin@cnri.reston.va.us] Sent: den 11 maj 1998 15:56 To: doc-sig@python.org Subject: [Doc-SIG] gendoc 0.71 patch 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 '

' and
'

' and
>'

' and
>'

' 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/ Life at the top is financially rewarding, spiritually draining, physically exhausting, and short. -- Peter C. Newman, _The Canadian Establishment_ (1975) _______________________________________________ Doc-SIG maillist - Doc-SIG@python.org http://www.python.org/mailman/listinfo/doc-sig From MHammond@skippinet.com.au Fri May 22 00:45:06 1998 From: MHammond@skippinet.com.au (Mark Hammond) Date: Fri, 22 May 1998 09:45:06 +1000 Subject: [Doc-SIG] gendoc 0.71 patch Message-ID: <00eb01bd8513$f2100190$0a01a8c0@skippy.skippinet.com.au> >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. From friedrich@pythonpros.com Sat May 23 21:27:10 1998 From: friedrich@pythonpros.com (Robin Friedrich) Date: Sat, 23 May 1998 15:27:10 -0500 Subject: [Doc-SIG] gendoc 0.71 patch References: <00eb01bd8513$f2100190$0a01a8c0@skippy.skippinet.com.au> Message-ID: <3567311D.3DBD6BB2@pythonpros.com> Right you are, Mark. I was really hopeful back then when everyone was chiming in with ideas. We (doc-sig) do need to follow up though with some commitments of code. (HINT HINT) Mark Hammond wrote: > > >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 :-) > -- Robin K. Friedrich Houston, Texas Python Professional Services, Inc. friedrich@pythonpros.com http://www.pythonpros.com Python Rules! From Daniel.Larsson@vasteras.mail.telia.com Mon May 25 22:19:44 1998 From: Daniel.Larsson@vasteras.mail.telia.com (Daniel Larsson) Date: Mon, 25 May 1998 23:19:44 +0200 Subject: [Doc-SIG] RE: gendoc bug In-Reply-To: Message-ID: <000001bd8822$d9209a20$4abc43c3@Daniel.telia.com> 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/